Video operations API

An ordinary active API key and your current access determine the models, routes and operations you can use. History belongs to the permitted owner, actor, selected key and group. A different key does not inherit it. Domain/IP policy also applies. The API host in these examples is https://api.model-gate.com; use the enabled host of your current service profile or custom domain instead when applicable. Do not use a temporary browser permission as a CLI key.

Methods

These are the service's dedicated video methods. Create and quote accept JSON, not the supplier's multipart interface. This is a bounded text/image-to-video workflow, not a general-purpose video SDK passthrough. A protocol/model name does not guarantee current availability; select an offer currently returned for your key. Reviewed reference images are described below. Remix, editing, cancellation, synchronous video responses and generation through generic Async/Batch are not supported here.

Request and quote

Required fields: model and a nonblank prompt. seconds is a decimal integer string. Depending on the offer, output settings use a supported size (WIDTHxHEIGHT), resolution plus aspect_ratio, or aspect_ratio alone; do not mix these forms. Duration and aspect-ratio-only offers do not accept a pixel size or resolution. Omitted settings use that offer's explicit defaults. Its catalog request fields, including request.prompt_max_chars, define what is accepted. Unsupported settings, duplicate JSON keys, unknown fields, binary/multipart input and an oversized JSON body are rejected. The JSON body limit is12MiB including base64 inputs; your service profile can be stricter. Read max_request_bytes in the catalog.

Optional model_gate: route_id identifies a returned offer; async can only be true (this operation is always asynchronous); quote_sha256 is the64-hex fingerprint from the price check. False async is not a request to wait indefinitely.

Send the same settings to POST /v1/videos/quote. It returns route_id, model, quote, quote_sha256, charged:false and provider_health_verified:false. It creates no generation, debit or reservation. Prices use the disclosed rate per completed video or per second, with current applicable coefficients. The duration source and whether the amount is an estimate are explained below. File size is not a price input. Refreshing a quote never submits a paid request.

For explicit price confirmation, retain the returned fingerprint in the create request. Playground does not send max_cost_usd. Changed price context is rejected as video_quote_changed. Runtime capacity and eventual supplier success are not reserved by a quote.

# A paid action: choose model and settings that your catalog actually offers.
curl --fail-with-body 'https://api.model-gate.com/v1/videos' \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-video-0001' \
  --data '{"model":"YOUR_ALLOWED_VIDEO_MODEL","prompt":"A small paper boat on still water","seconds":"4","size":"1280x720","model_gate":{"async":true}}'

The duration and dimensions above are illustrative, not a universal model guarantee. Copying does not run the command. Executing it may incur a charge. Do not add an automatic --retry around a paid create.

Estimates and final cost

Read quote.kind before creating an operation:

For offers with quote.duration_source equal to original_mp4, a per-second estimate uses the requested duration before launch. The final charge uses the measured duration of the original validated MP4, which can differ from the requested duration. The final usage.seconds is an exact decimal string and can include a fractional second; the input seconds remains an integer string. A price per completed video remains fixed for that one video. The separate quote.usage_kind describes the Usage Limit valuation, which can have its own estimate or final calculation. Other offers keep their existing validated completion-duration calculation.

A create request with model_gate.max_cost_usd and quote.kind=estimate returns HTTP422 with video_cost_ceiling_not_guaranteed before paid generation, even when the estimate is below the requested ceiling. A fixed quote remains subject to the normal ceiling check. If your integration requires a hard ceiling, select an offer with a fixed quote. quote_sha256 confirms the selected settings and price context; it does not turn an estimated duration into a guaranteed maximum. Missing or invalid media does not produce an invented zero duration or a repeated generation.

Identity and lifecycle

Creation requires one Idempotency-Key:1–128 printable non-space ASCII characters. The same key and validated unchanged intent returns the existing operation; changed intent returns409. Model, prompt, normalized settings, explicit route and price conditions participate in identity. Keep the same key and actor context; using a new key or intent is not a safe retry of an unknown paid outcome. Records survive file expiry.

Accepted create returnsHTTP202, a Location and local operation ID. Replaying an already completed intent can return200 with the same operation, not a new movie. Check status: HTTP200 on a read or202 on queue acceptance does not mean the supplier finished.

States progress through queued, preparing, dispatching, received, polling, retrieving and completed. Some fast stages may not be observed, and not every offer uses polling. An accepted operation may wait in dispatching and then move directly to receiving and validating its result. provider_progress is omitted when unavailable, otherwise the supplier-reported percentage; it is not an ETA. The explicit details view can include supplier_http_status and last_poll_http_status; these are not part of the compact default. Closing the page does not cancel an accepted operation.

There is no automatic paid retry after an ambiguous create. outcome_unknown requires Support; review_required means saved evidence needs review; retrieval_failed means an already generated result could not be obtained or verified. A failed download is not permission to generate again. Bounded checks may stop with video_poll_deadline; they do not guarantee the supplier stopped its work. Report the operation ID and safe code rather than sending a duplicate.

History, MP4 and access

GET /v1/videos/operations returns up to50 scoped entries with next_cursor; pass it as before for older entries. ?idempotency_key=... performs a read-only lookup and returns submission_found. Momentary absence is not evidence that an in-flight create did nothing.

A completed detail/result contains a file descriptor with MIME, bytes, SHA-256, dimensions and duration. /result is a JSON manifest. /content is the actual private video/mp4, supports authorized Range reads and ?download=1, and never generates a new movie. Every read requires current authorization. The completed format is MP4 with H264 video and optional AAC audio; supported offers are bounded to30seconds,4096pixels per dimension and128MiB, and may be stricter. Files normally expire24hours after creation. Missing, expired or corrupt content is not regenerated by reading it.

An operation may have a recorded price even when later file retrieval failed. In the explicit details view, accounting_recorded means an accounting input exists, not a completed wallet debit. The settlement observation separates pending, settled/recovered, unavailable and retained-record absence. Only an actual observed settled/recovered positive amount is labelled Debited; Usage Limit and wallet money are distinct. Historical result/settlement rows may no longer be available. Reading a paid result does not require a positive current balance, but current rights remain mandatory.

Errors and inspection

Typical input problems:400 invalid fields/idempotency,403 revoked scope or changed grant body,409 idempotency conflict,413 JSON too large,415 wrong Content-Type,422 unsupported settings or changed quote,429 capacity/limits,503 unavailable catalog/service. Inspect the safe error.code rather than assuming every503 means no work. For an operation, a nonempty error_code accompanies its durable state and may represent a supplier failure even though the state GET returned200.

Playground Raw response shows the service response it actually received, including errors and whitespace, not secret supplier headers. Raw data must remain private. Sharing a prompt, credential or downloaded response publicly is not required for Support to locate an operation.

Route-specific output settings

Some available routes accept resolution and aspect_ratio instead of size. Read the selected route in GET /v1/videos/catalog; do not combine these fields with size. seconds remains a string in this API. The catalog provides the allowed values and defaults. Unsupported input images or references are rejected rather than silently omitted.

{"model":"YOUR_AVAILABLE_VIDEO_MODEL","prompt":"A paper boat on a quiet lake","seconds":"6","resolution":"720p","aspect_ratio":"16:9","model_gate":{"async":true}}

Send this body to the current account API's POST /v1/videos with your API key and one retained Idempotency-Key. Quote the same parameters with POST /v1/videos/quote first; changing them invalidates the previous quote. A compatible route may allow 1–15 seconds and a subset of the resolution values below; the selected catalog, not this example, defines your available options. The result remains the authorized saved MP4; third-party result URLs are not public client download links.

Resolution-based offers can expose 480p, 720p, 1080p, 1440p, 2160p, 2k, 2K, 4k or 4K. Use only an exact value returned in the selected offer's request.resolutions; availability depends on the model and your account. Here 2k/2K designate a 1440-pixel short edge, and 4k/4K designate a 2160-pixel short edge, not DCI widths. Spelling and case are preserved in quotes and creation requests. Do not replace one value with an alias after checking the price: select the offered value and obtain a fresh quote for it. These accepted labels do not promise that every model offers every resolution.

Duration and aspect ratio only

Other text-only offers accept seconds and aspect_ratio without size or resolution. They reject image and reference_images. Their catalog request settings include request.seconds, request.default_seconds, request.aspect_ratios and request.default_aspect_ratio. These offers can expose durations from 1 to 20 seconds and the aspect ratios 16:9, 9:16, 1:1, 4:3 and 3:4; each selected model may allow only a subset. Use the returned values and defaults.

{"model":"YOUR_AVAILABLE_VIDEO_MODEL","prompt":"A paper boat on a quiet lake","seconds":"4","aspect_ratio":"16:9","model_gate":{"route_id":"YOUR_OFFERED_ROUTE","async":true}}

Creation still uses POST /v1/videos and returns an asynchronous local operation. If supplied, model_gate.async remains true. Read that operation's status and saved result using the methods above; the duration/aspect-ratio settings do not require a different client submission method.

Compact status and accounting details

Since version11.0.0, operation responses are compact by default: object, id, model, status, created, status_url, result_url. An actionable error_code or reported progress is included only when present. Completed results include availability, expiry and required file descriptors. Empty fields, quote, normalized usage, settlement and supplier diagnostics are omitted. Omission does not mean zero cost or a completed debit.

Use GET /v1/videos/operations/{id}?view=details for the previous full authorized accounting view. Lists and result manifests also support the explicit details view where applicable. Reading details never generates new media or expands access. The quote endpoint remains the separate place to inspect an uncharged price calculation.

Optional reference inputs

Read the selected offer's request.reference_images object first. Its modes, max_images, mime_types, max_image_bytes, max_total_bytes and max_pixels are binding limits. No object means text-only. Use image for one first frame, or reference_images for a set, never both. Only inline PNG/JPEG/WebP data URLs are accepted; external input URLs and file IDs are not accepted. The server verifies actual raster content. Some first-frame offers require exactly the selected output dimensions.

{"model":"YOUR_ALLOWED_VIDEO_MODEL","prompt":"A calm scene","seconds":"6","resolution":"720p","aspect_ratio":"16:9","image":{"url":"data:image/png;base64,REPLACE_WITH_IMAGE_BYTES"},"model_gate":{"route_id":"YOUR_OFFERED_ROUTE","async":true,"quote_sha256":"YOUR_QUOTE_FINGERPRINT"}}

For a supported reference set, replace image with "reference_images":[{"url":"data:image/png;base64,..."},{"url":"data:image/jpeg;base64,..."}]. The examples are not executable with placeholders. Quote the exact same inputs/settings first and retain the fingerprint and one Idempotency-Key for creation. Different input modes can have different rates; a model name alone does not enable reference support.

Read a result: Raw and cURL

Use the same active API key and actor context that created the operation. Another key under the same account does not automatically inherit its results. Current access and domain/IP restrictions are checked again. Get OPERATION_ID from the accepted creation response or your authorized history, and set MODEL_API_KEY locally without publishing the secret. A temporary Playground permission is not a reusable CLI credential; copying a command does not export or enlarge that permission.

GET https://api.model-gate.com/v1/videos/operations/{id}/result
Authorization: Bearer <YOUR_API_KEY>

# status
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video-status.json

# result
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}/result" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video-result.json

# MP4
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}/content" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video.mp4

/result is a JSON manifest. To save the actual movie, use /content and an .mp4 filename. Saving the manifest as .mp4 does not turn it into a video. The local operation ID is the ID from this API, not a supplier task ID.

These are bodyless GET requests: no Content-Type, Idempotency-Key, quote, route_id or max_cost_usd is needed. Read status until it reports completion, then read the result/file. Pending, failed, expired and unauthorized responses are not output files; --fail-with-body returns a nonzero exit status for HTTP errors but may still write their body to the output filename. Check the status and content type before treating a downloaded body as media. Do not repeat a paid POST because a GET failed.

Playground's Get the result · Raw / cURL block generates these commands for the selected operation and its original key. They are examples of a new read, not a recording of an earlier HTTP exchange. Copying or switching command tabs makes no network request. Opening history or a saved result still performs its normal authorized read; it does not generate, reserve or charge again.