Create generation task

POST/api/v1/generation-tasks

Submit a generation task with a model slug from GET /api/v1/models. The input object is dynamic per model and must follow that model input_schema. Pass template_id from GET /api/v1/templates to start from a ready-to-use preset.

Authorization

MagerApiKey

x-mager-api-key<token>

Mager API key

In: header

Header Parameters

x-mager-api-key*string

Mager API key

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

callback_url?string

Optional webhook URL called when the task reaches finished or failed. Every delivery carries x-mager-timestamp and x-mager-signature; verify with sha256=HMAC_SHA256(webhookSecret, ${timestamp}.${rawBody}) over the raw request body, compare in constant time, and reject timestamps older than five minutes. The secret comes from GET /api/v1/developers/account.

Formaturi

Lengthlength <= 2048

idempotency_key?string

Optional client-generated key that makes this call safe to retry. A repeat call with the same key returns the original task instead of generating and charging again, including when that task failed. Use a fresh key for a genuinely new generation.

Length1 <= length <= 255

input?

Dynamic input object. Follow the input_schema from GET /api/v1/models or the default input from GET /api/v1/templates.

Default{}

model*string

Model slug returned by GET /api/v1/models. Example: image-generator, text-generator, or a service-backed model slug.

Length1 <= length <= 160

model_tier?string

Optional tier name (e.g. lite, max). If not provided, fallback to the service default model.

Length1 <= length <= 50

output_count?integer

Number of outputs to generate.

Range1 <= value <= 10

Default1

template_id?string

Optional template ID returned by GET /api/v1/templates. Use this for ready-to-use presets.

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/generation-tasks" \  -H "x-mager-api-key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "image-generator",    "model_tier": "max",    "input": {      "prompt": "Studio product photo of a cold matcha latte bottle",      "aspectRatio": "1:1",      "style": "clean commercial lighting"    },    "callback_url": "https://client.example.com/webhooks/mager",    "output_count": 1  }'

{  "status": 201,  "message": "Success",  "data": {    "task_id": "cmagr01hxyz123",    "status": "running",    "model": "image-generator",    "template_id": null,    "callback_url": "https://client.example.com/webhooks/mager",    "created_at": "2026-07-03T06:00:00.000Z",    "updated_at": "2026-07-03T06:00:00.000Z",    "completed_at": null,    "error": null,    "billing": {      "base_moods": 10,      "charged_moods": 15,      "extra_moods_charged": 5    },    "result": [],    "webhooks": [      {        "id": "delivery_01hxyz",        "status": "PENDING",        "attempts": 0,        "max_attempts": 3,        "last_attempt_at": null,        "next_retry_at": null,        "delivered_at": null,        "last_status_code": null,        "last_error": null      }    ]  }}

Create generation task

Authorization

Header Parameters

Request Body

Response Body

201application/json

401application/json

404application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`