REST API

API is hosted at https://api.machgen.ai.

The general task lifecycle is always the same: submit a task, poll its status until it completes, then download the result.

To check your balance or usage, see Account and Billing. Some models take extra options, covered under Model Specifics:

• MiniMax H3
• Seedance 2.0
• Seedance 2.5
• Wan 3.0

To generate with your own LoRA, see Custom LoRAs.

Depending on the exact task, the task input may require specific fields. Please refer to the following example for details.

Provide your API key

Send your key (see Get Started) as a bearer token on every request:

# Key starts with `MGA_`
export MACHGEN_API_KEY=".."

curl -H "Authorization: Bearer $MACHGEN_API_KEY" https://api.machgen.ai/..

Submit a task

POST /api/v0/generate with a JSON TaskInput describing the task. It returns immediately with a task_id - it does not wait for generation. The body fields differ per task type.

Check the following examples to get a quick start.

For detailed API input/output reference, refer to the API Reference page.

curl https://api.machgen.ai/api/v0/generate \
  -H "Authorization: Bearer $MACHGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red panda exploring a misty forest at dawn",
    "model": "Wan2.2-A14B",
    "task_type": "T2V",
    "video_config": {"duration_secs": 5, "height": 720, "aspect_ratio": "16:9", "fps": 16, "infer_steps": 30}
  }'

The response carries the task_id you poll and download with:

{ "task_id": "t-abc123", ... }

Check status and download

Poll GET /api/v0/tasks/{task_id} until status is COMPLETED or FAILED.

curl -H "Authorization: Bearer $MACHGEN_API_KEY" \
  https://api.machgen.ai/api/v0/tasks/t-abc123

To skip polling, pass webhook_url (an HTTPS URL on a public host) with the generate request. When the task finishes we POST this same status response to it once, with the task id in the X-Task-Id header. If your endpoint does not answer with a 2xx we retry for a while, so treat a repeat as the same event. You can check whether each webhook was delivered under Webhooks on your profile page.

{
  "task_id": "t-abc123",
  "status": "COMPLETED",
  "metadata": {
    "prompt": "...",
    "height": 720,
    "width": 1280,
    "fps": 24,
    "duration_secs": 5,
    ...
  },
  "task_output": {
    "video": "https://api.machgen.ai/api/v0/assets/t-abc123"
  }
}

curl -H "Authorization: Bearer $MACHGEN_API_KEY" \
  https://api.machgen.ai/api/v0/assets/t-abc123 -o output.mp4

A task moves through these statuses; COMPLETED and FAILED are terminal:

Check what a task cost

Once a task is COMPLETED or FAILED, GET /api/v0/tasks/{task_id}/billing returns what it cost, the Generation Credit it earned back, and the net.

curl -H "Authorization: Bearer $MACHGEN_API_KEY" \
  https://api.machgen.ai/api/v0/tasks/t-abc123/billing

{
  "task_id": "t-abc123",
  "generation_cost_micros": 2000000,
  "generation_credit_micros": 200000,
  "net_cost_micros": 1800000
}

Amounts are in millionths of a dollar. A failed or canceled task is refunded and reports 0. The cost is not final while the task is still PENDING or RUNNING, so asking before then returns 409 Conflict; poll the status first. See TaskBillingResponse for the fields.

Cancel a task

A queued task can be canceled before it starts. Cancel is best effort: if the task is still PENDING, it stops there and the charge is refunded. Once it is RUNNING the request is ignored and the task finishes normally. A multi-stage task counts as started as soon as any stage has started.

curl -X POST -H "Authorization: Bearer $MACHGEN_API_KEY" \
  https://api.machgen.ai/api/v0/tasks/t-abc123/cancel

The response is the same status object returned by GET /api/v0/tasks/{task_id}, read after the cancel. A canceled task shows as FAILED with an error_msg that says it was canceled; a task that had already started shows its current status instead. Calling cancel on a finished task is safe and changes nothing.

{
  "task_id": "t-abc123",
  "status": "FAILED",
  "error_msg": "The task was canceled before it completed. Any charge was refunded."
}

If the task has a webhook_url, the webhook is still delivered, with this same response.

Error Codes

A FAILED status (above) reports a task that was accepted but could not be generated. A request that is rejected before acceptance instead returns a non-2xx HTTP status with a JSON body carrying a single detail string:

{ "detail": "Wan2.2-T2V-A14B does not support height=1080; allowed heights: [480, 720]" }

Sync mode

For self-hosted models you can skip the poll-and-download round trip and receive the finished result inline. POST /api/v0/generate/sync takes the same JSON TaskInput body, but the request blocks until the worker streams back the encoded result and returns those bytes directly.

Sync mode is available for:

• T2I and I2I tasks on self-hosted (non-passthrough) models, returning image/jpeg;
• selected self-hosted video surfaces that generate fast enough to answer within the wait, returning video/mp4. On a model with a prompt enhancer, POST /api/v0/generate/sync enhances by default exactly as POST /api/v0/generate does - that call runs inside your wait, so send "enhance_prompt": false if you would rather start generating sooner.

Everything else returns 400.

curl https://api.machgen.ai/api/v0/generate/sync \
  -H "Authorization: Bearer $MACHGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An isometric illustration of a cozy reading nook, soft lighting",
    "model": "FLUX.2-dev",
    "task_type": "T2I",
    "image_config": {"width": 1024, "height": 1024}
  }' -o output.jpg

On success the response is 200 OK with the raw encoded bytes as the body - image/jpeg for an image task, video/mp4 for a video one. The X-Machgen-Delivery-Mode header says which (sync-image or sync-video), and X-Machgen-Task-Id carries the task id: the durable task may still be finalizing when you receive the bytes, so use that id to poll status or fetch the canonical asset later, exactly as with an async task.

If the result cannot be delivered inline - generation runs past the timeout, the result is oversize, or an inline error occurs - the server falls back to the async path and returns 202 Accepted with the normal GenerateResponse JSON body plus an X-Machgen-Sync-Fallback-Reason header (timeout, oversize, or inline_error).

A fallback is not a failure: the task continues on the async path and can be polled and downloaded exactly like one submitted to POST /api/v0/generate.

Inline source images (sync only)

To skip the source-upload round trip on latency-sensitive I2I requests, the sync endpoint also accepts inline base64 entries in src_image_urls using the standard data-URL form:

{
  "task_type": "I2I",
  "src_image_urls": ["data:image/png;base64,iVBORw0KGgo..."]
}

The server verifies the bytes at admission, stores a durable copy in your upload space, and the task's metadata echoes a normal @input/... ref - after acceptance an inline source is indistinguishable from an uploaded one. Each inline image is capped at 1 MB of raw bytes (about 1.37 MB encoded - base64 inflates by about a third); larger images must be uploaded instead. The Python SDK ships a size-guarded helper, machgen.client.inline_image_source(path), that encodes a local file into this form.

Inline sources are accepted only on /v0/generate/sync; POST /api/v0/generate rejects them with a 400.

Source images

For I2V, R2V, and I2I, every entry in src_image_urls must be a public http(s):// URL. (On POST /api/v0/generate/sync only, an entry may instead be an inline data:image/...;base64, URL - see Inline source images.)

For I2V the list is positional: entry 0 is the start frame, and an optional entry 1 is the end frame. To animate from a single image, pass one URL; to pin both ends of a clip, pass two.

{
  "task_type": "I2V",
  "src_image_urls": ["https://example.com/first-frame.png", "https://example.com/last-frame.png"]
}

An end frame is supported by Alibaba-Wan-3.0, the Seedance-2.0 family, Kling-v3, LTX-2.3-Pro, Vidu-Q3-Turbo and Vidu-Q3-Pro. Every other model accepts one image only and returns HTTP 400 for a second, rather than discarding it. A third image is always a 400.

To animate towards a single image instead, mark it as the end frame with keyframe_indices. The list is aligned 1:1 with src_image_urls: 0 is the start frame and -1 the end frame, so [0], [0, -1] and [-1] are the accepted values, and omitting it keeps the positional reading above. A lone end frame is supported by MiniMax-H3; other models return HTTP 400 for it.

{
  "task_type": "I2V",
  "src_image_urls": ["https://example.com/last-frame.png"],
  "keyframe_indices": [-1]
}

Reference video and audio

At least one image or video is required - audio alone returns HTTP 400. Seedance-2.0-Fast and Seedance-2.0-Mini also cap the combined image, video, and audio reference count at 12.

A prior MachGen generation can be referenced by task id in src_task_ids instead of a URL: each id is routed to src_video_urls, src_image_urls, or src_audio_urls by the source task's output type, appended after any URLs already in that list. Subject maps (subject_to_*_ids) index the lists as they stand after that routing.

A public http(s):// entry in src_video_urls (a signed link included) is checked for reachability at submit time with a lightweight request; a link that does not answer with success is rejected with HTTP 400 input not accessible: <url> (<reason>) before the task is admitted.

Name a reference with the matching subject map and address it in the prompt as @name. Whitespace in a submitted name is normalized to _ together with its matching prompt mention; names that collide after normalization return HTTP 400. A name may appear in only one map. Once any subject is named, every unquoted @handle in the prompt must match a subject - the request is rejected with HTTP 400 otherwise. To keep a literal @handle as plain prompt text (a screen name, for example), quote it: "@handle".

curl https://api.machgen.ai/api/v0/generate \
  -H "Authorization: Bearer $MACHGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@alice dances to @beat in the style of @routine",
    "model": "Seedance-2.0",
    "task_type": "R2V",
    "src_image_urls": ["https://example.com/alice.png"],
    "src_video_urls": ["https://example.com/routine.mp4"],
    "src_audio_urls": ["https://example.com/beat.mp3"],
    "subject_to_image_ids": {"alice": [0]},
    "subject_to_video_ids": {"routine": [0]},
    "subject_to_audio_ids": {"beat": [0]},
    "video_config": {"duration_secs": 5, "height": 720, "aspect_ratio": "16:9", "fps": 24}
  }'

A reference video can be read from an offset instead of its start with reference_video_start_secs, aligned 1:1 with src_video_urls (as the list stands after src_task_ids routing) and given in seconds. The offset must fall inside the clip, and what remains after it is what the model sees, what counts towards the combined duration limit, and what is billed. Omitted, every clip is read from 0. A non-zero offset is supported by MiniMax-H3; other models return HTTP 400 for it.

{
  "task_type": "R2V",
  "src_video_urls": ["https://example.com/a.mp4", "https://example.com/b.mp4"],
  "reference_video_start_secs": [2.5, 0]
}

Request and response reference

The full field reference for the request body (TaskInput, VideoConfig, ImageConfig) and the status response (TaskStatusResponse) lives on the API Reference page.