Mager API

Quickstart

From an API key to a finished image in four requests.

This walks through one complete generation. Every request uses the same key, sent as the x-mager-api-key header.

1. Get an API key

Open the Mager dashboard, request a developer account, and create a key once the account is approved. The plaintext key is shown once, at creation. Store it somewhere your application can read it — it cannot be retrieved again.

Keys look like this:

mager_sk_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f4c

Treat it like a password. It is a server-side credential; never ship it in a browser or a mobile app. See Authentication for scopes and key rotation.

2. Find a model

curl https://api.mageran.ai/api/v1/models \
  --header 'x-mager-api-key: YOUR_API_KEY'

Each entry has a model slug and an input_schema describing the keys that model accepts:

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "model": "image-generator",
      "title": "Image Generator",
      "capability": "IMAGE_GENERATION",
      "default_output_count": 1,
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": { "type": "string" },
          "aspectRatio": { "type": "string", "enum": ["1:1", "9:16", "16:9"] }
        },
        "required": ["prompt"]
      },
      "model_tiers": ["lite", "max"]
    }
  ]
}

Read input_schema rather than hardcoding fields. It is the contract for step 3, and it differs per model.

3. Create a task

curl https://api.mageran.ai/api/v1/generation-tasks \
  --request POST \
  --header 'x-mager-api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "model": "image-generator",
    "model_tier": "max",
    "input": {
      "prompt": "Studio product photo of a cold matcha latte bottle",
      "aspectRatio": "1:1"
    },
    "output_count": 1
  }'

The response comes back immediately with a task_id and a status of queued or running. Generation happens in the background.

{
  "status": 201,
  "message": "Success",
  "data": {
    "task_id": "cmagr01hxyz123",
    "status": "running",
    "model": "image-generator",
    "billing": { "base_moods": 10, "charged_moods": 15, "extra_moods_charged": 5 },
    "result": []
  }
}

4. Wait for the result

Poll the task until its status is finished or failed:

curl https://api.mageran.ai/api/v1/generation-tasks/cmagr01hxyz123 \
  --header 'x-mager-api-key: YOUR_API_KEY'
{
  "status": 200,
  "data": {
    "task_id": "cmagr01hxyz123",
    "status": "finished",
    "completed_at": "2026-07-03T06:01:00.000Z",
    "result": [
      {
        "id": "result_01hxyz",
        "status": "SUCCESS",
        "file_url": "https://cdn.example.com/generated-image.png",
        "file_type": "image/png"
      }
    ]
  }
}

Poll every few seconds, not every few hundred milliseconds — polling counts against your rate limit.

Better: pass a callback_url when you create the task and Mager will call you instead. See Webhooks.

Next

Models and templates

Start from a preset instead of writing every input field.

Task lifecycle

What each status means and when to stop polling.

Clipping Engine

Cut clips, build highlight reels, and transcribe video.

Errors

The error envelope and what each status code means.

API reference

Every endpoint in detail.

On this page

1. Get an API key2. Find a model3. Create a task4. Wait for the resultNext