Video generation

Video generation is asynchronous: a three-step job flow. The prompt goes in the submit request and is fixed at submit time; the later calls only reference the job id.

1. Submit

$
curl -X POST https://api-gateway.merge.dev/v1/videos \
>
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "minimax/minimax-h3",
>
    "prompt": "a red ball rolling on grass",
>
    "seconds": 4
>
  }'

Returns 202 Accepted with a job: {"id": "vid_...", "status": "queued", ...}.

Optional parameters: seconds (clip duration; model-specific limits) and size (output resolution, e.g. "1080P", which selects the per-second rate on resolution-tiered models).

2. Poll

$
curl https://api-gateway.merge.dev/v1/videos/vid_XXXX \
>
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY"

Poll until status is "completed" (generation typically takes one to a few minutes depending on the model). The completed response includes the final cost. A "failed" status carries the provider error.

3. Download

$
curl https://api-gateway.merge.dev/v1/videos/vid_XXXX/content \
>
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
>
  -o video.mp4

The /content response is the raw MP4. Requesting it before the job completes returns a JSON error instead of bytes. If a downloaded file won’t play, inspect it (file video.mp4): JSON data means you saved an error body, so poll until completed and download again.

Billing

Video bills per output second (unit: per_second), with resolution tiers under output_per_second_by_resolution on GET /v1/models. Billing settles when the job completes, at the served resolution and duration; the settled amount is echoed as cost on the completed job. Submissions are also preflighted against customer budgets using the requested duration and tier rate.

Jobs are scoped to your organization (and to the request’s customer, if you scope requests to projects); keys from another organization cannot see or download them.

Next steps