Video generation task API

Beginner: submit, finish, and download are separate

For Seedance videos using real-person photos or multiple portrait references, follow the complete real-person video tutorial: upload each image, start review, wait for active, then submit video creation with its asset:// reference. The tutorial includes a full script, parameter tables, and review-task tracking.

Video generation can take seconds or minutes. POST /v1/videos creates a task; persist its id or compatibility field task_id, then query GET /v1/videos/{task_id}. Read output only at status=completed. queued and in_progress are intermediate states, while failed is terminal. The gateway also exposes /v1/video/generations for compatible clients; select one contract and do not mix their response fields.

MiniMax-H3 official V2 and OpenAI remix

The gateway supports MiniMax-shaped POST /v2/video_generation, POST /v2/video_regeneration, POST /v2/h3_context_ir, and GET /v2/query/video_generation/{task_id}, plus OpenAI-compatible POST /v1/videos/{video_id}/remix. Every ID in a create or query response is a gateway system Task ID. The gateway authorizes and internally maps source_task_id and path video_id values to private upstream task IDs; clients must not store, submit, or depend on a real upstream ID.

Official paths are fixed and never auto-switch: /v2/video_generation always validates the strict generation schema and calls generation, /v2/video_regeneration always validates the strict regeneration schema and calls regeneration, and /v2/h3_context_ir always creates an enhanced-prompt task. A body shaped like another operation is rejected instead of silently rerouted.

Only POST /v1/videos uses strong-evidence auto-routing. A non-empty source_task_id or exactly one base_video selects regeneration; reference_video remains generation; no strong regeneration evidence also selects generation. Conflicts return HTTP 400, including simultaneous source and base modes, multiple or empty base videos, and an explicit action that contradicts the body. Rejection happens before source lookup, media work, billing, persistence, or provider I/O.

Every channel retry restores the client path, body, and media references from the immutable original request, then repeats classification, validation, system source Task ID resolution, and representation selection for the current credential. An earlier attempt's action, mapped model, content, staging URL, or real upstream ID never becomes the next attempt's input. Clients always receive the system Task ID; the real upstream Task ID is stored only in the private mapping.

Normal H3 V2 generation keeps the official request fields. Set duration, resolution, and ratio within the model's supported ranges; creation still returns only a system Task ID.

MiniMax-H3 official Context-IR request

POST /v2/h3_context_ir creates an asynchronous enhanced-prompt task; it does not generate a video. The request must be JSON and its exact wire model must be MiniMax-H3. The only allowed top-level fields are model, content, duration, ratio, and optional callback_url. The server derives and injects the task type from the path, so a client-supplied task_type returns HTTP 400 on this official endpoint. The endpoint also rejects resolution, aigc_watermark, top-level prompt, action, source_task_id, metadata, seconds, size, and every unknown field.

content must be a non-empty array with at least one non-empty text item, and each text item is limited to 7,000 Unicode code points. duration must be an integer from 4 through 15. Text-only input requires an explicit valid ratio other than adaptive; first-frame-only, last-frame-only, first-and-last-frame, or reference-media input may omit the ratio. Context-IR follows its endpoint-level OpenAPI support for text + last_frame; this does not relax ordinary generation or regeneration. If present, callback_url is forwarded unchanged to Hailuo.

Copy{
  "model": "MiniMax-H3",
  "content": [{"type": "text", "text": "Expand this idea into a structured video prompt"}],
  "duration": 5,
  "ratio": "16:9",
  "callback_url": "https://callback.example/context-ir"
}

A successful create response contains only the gateway system task_id. Continue with GET /v2/query/video_generation/{task_id}. On success, the enhanced prompt appears at task.content.prompt, not as a video URL at task.content.url.

MiniMax-H3 V2 official generation payload

Reference: MiniMax-H3: Create a video generation task (official). Use this gateway's base URL, token and system task_id, not the upstream credentials or task IDs in the official example.

Copy{
  "model": "MiniMax-H3",
  "content": [{"type": "text", "text": "A paper-cut rabbit crossing a misty forest"}],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}

Official /v2/video_generation does not accept or convert a top-level prompt; that flat shape belongs only to the /v1/videos compatibility entrypoint. The official path always validates the native raw schema and returns a local parameter error for compatibility-only fields.

An official regeneration request must use MiniMax-H3, explicitly set resolution to 2K, and select exactly one input mode. The source-task mode refers to an eligible successful task in the same MiniMax account:

Copycurl "$BASE_URL/v2/video_regeneration" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "system-source-task-id",
    "resolution": "2K",
    "aigc_watermark": false
  }'

The base_video mode supplies one video satisfying the official constraints. It cannot coexist with source_task_id and should preserve the final prompt and original reference media in content.

MiniMax-H3 V2 official content regeneration payload

Copy{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "content": [
    {
      "type": "video_url",
      "role": "base_video",
      "video_url": {"url": "https://media.example.com/source.mp4"}
    },
    {"type": "text", "text": "the final prompt used for the source task"}
  ]
}

An OpenAI client can put the system Task ID in the remix path; the gateway converts it to the same native regeneration operation:

Copycurl "$BASE_URL/v1/videos/system-source-task-id/remix" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-H3","resolution":"2K"}'

Official creation returns {"task_id":"<system-task-id>"}. Poll that value with GET /v2/query/video_generation/{task_id}; an OpenAI client polls GET /v1/videos/{task_id}. The same task is rendered in the dialect selected by the query path. Official MiniMax regeneration upgrades only a source that meets the MiniMax-H3 768P output constraints to 2K; it is not a general transcoder or arbitrary upscaler.

Regeneration has a dedicated pricing key, MiniMax-H3__regeneration. A missing contract fails before upstream submission, while an explicit zero price remains valid. Pre-consumption uses frozen request and pricing facts. Success settles from real upstream usage when available, falls back to the frozen estimate when usage is absent, and retains the frozen pre-consumption when the corresponding token or seconds facts are still unavailable. Failure follows asynchronous refund rules, and terminal CAS plus a unique financial event prevents duplicate settlement. External HTTP(S), data URLs, local content proxies, MiniMax file references, and /ximg/ inputs share protected downloading, type and size checks, staging, and channel URL conversion. Retries rebuild from the frozen original media, and successful responses expose only the processed or accelerated client URL.

Minimal create and poll example

Copycreate=$(curl -sS "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sora-2","prompt":"A paper-cut rabbit crossing a misty forest","seconds":"8","size":"1280x720"}')

task_id=$(printf '%s' "$create" | jq -r '.id // .task_id')
test -n "$task_id" && test "$task_id" != "null"

curl "$BASE_URL/v1/videos/$task_id" \
  -H "Authorization: Bearer $API_KEY"

A status object may include progress, created_at, completed_at, expires_at, video_url, and error. HTTP 200 alone is not a success condition because the task can still contain failed.

State machine, deadlines, and retries

Model the expected path as queued → in_progress → completed|failed. Preserve and alert on an unknown status instead of silently treating it as success. Begin polling around two to five seconds, back off with jitter, and impose an overall business deadline. A network timeout does not prove create failed. Reconcile an application idempotency key, Request-ID, or previously stored task ID before resubmitting to prevent duplicate work and billing.

Status reads are naturally retryable. Create and remix operations need a verified idempotency contract. Do not automatically retry invalid parameters, authentication failures, or deterministic content rejection.

Inputs, downloads, and lifetime

Accept image inputs only through a channel-supported format and controlled HTTPS locations. Remote fetching needs SSRF protection, redirect limits, content-type checks, and byte, pixel, and duration bounds. After completion, use video_url or, where supported, GET /v1/videos/{task_id}/content. Stream the body with timeouts and a maximum length, verify its hash, and use an atomic temporary-file or object-storage write.

expires_at is a lifecycle signal, not permanent storage. Record task, owner, model, prompt version, media type, size, hash, retention date, and deletion status in your own storage catalog.

Production observability and billing

Measure submission success, queue delay, generation time, terminal success, failure codes, pre-expiry download rate, and model cost. Correlate internal task ID, upstream task ID, Request-ID, and user idempotency key without logging raw sensitive media. Reconcile duration, resolution, tier, count, and retries. Client disconnection does not necessarily cancel upstream work, so cancellation and billing semantics must be tested separately.

Expert: capacity, callbacks, and recovery

Isolate submission from polling with a queue and cap per-user and global in-flight work. Use leases so multiple workers do not poll the same task; make terminal writes idempotent. Verify callback signatures and replay protection when callbacks exist, but retain active polling as a recovery path. Exercise provider timeout, stuck tasks, expired links, storage failure, and duplicate callbacks before launch, and ensure final settlement or refund reconciles to the task terminal state.