Video Generation API

Video generation is asynchronous. Create an API key in the user center and ensure its group allows video generation and the selected model. The gateway adapts provider protocols; clients use the public model name and the unified JSON API.

Base URL and compatibility

The examples use an origin without /v1:

BASE_URL="https://your-api-host"
API_KEY="YOUR_MUSKAI_API_KEY"

If the copied Base URL already ends in /v1, append /videos instead of /v1/videos. The unified endpoint currently accepts JSON and remote media URLs. Official Videos SDK multipart file uploads are not adapted; use an ordinary HTTP request rather than assuming every SDK method works after changing its Base URL.

Create a task

Send POST /v1/videos with a Bearer key and JSON fields such as model, prompt, duration, aspect_ratio, and resolution (as supported by the model).

curl "$BASE_URL/v1/videos" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"A cinematic sunset by the sea","duration":5}'

POST /v1/video/generations is also available. Keep the same creation path when retrying. Streaming is unsupported.

Explicit provider adapters return a normalized object; save both id and idempotency_key:

{"id":"YOUR_TASK_ID","object":"video","status":"queued","model":"grok-imagine-video","idempotency_key":"YOUR_RETURNED_KEY"}

Parameters and references

Field	Meaning
model	Required public model name; check the model catalog and your key's group.
prompt	Scene, camera movement and subject description.
duration	Positive integer seconds; aliases: seconds, duration_seconds. Multiple duration fields must agree. Creation defaults to 8 seconds; explicitly setting it is recommended.
resolution	Model/channel-supported value such as 720p. Defaults depend on the provider protocol; explicitly setting it is recommended.
aspect_ratio	A ratio supported by the model, such as 16:9.
images, videos, audio	Reference arrays of URL strings or {"url":"https://..."} objects. audios aliases audio; this is reference audio, not an output-audio toggle.
first_frame, end_frame	Frame URL strings or URL objects; both count toward the image limit. Requires model support.
contains_real_person	Set to true for real-person content; real_person is an alias. Used for routing and removed before forwarding. Unmarked requests are treated as ordinary requests; prompts/images are not automatically classified.

The gateway filters channels by resolution, duration, real-person support and reference counts, including sticky selection and failover. Account limits do not imply that every model supports every feature. Do not mix native provider content references with canonical fields, or submit conflicting aliases. Common size values are matched by their shorter side: 1280x720 and 720x1280 match 720p. 2k and 4k are not guessed to mean 1080p and 2160p.

Reference example (replace the model and URLs with real, provider-accessible HTTPS assets; supported combinations vary by model):

{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "Keep the referenced person's appearance; slowly move the camera closer",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "contains_real_person": true,
  "images": ["https://your-public-host.example/reference.jpg"],
  "videos": ["https://your-public-host.example/reference.mp4"],
  "audio": ["https://your-public-host.example/reference.mp3"]
}

Idempotency and retries

If you omit Idempotency-Key, the server generates a random key and returns it in JSON idempotency_key and the Idempotency-Key / X-Idempotency-Key response headers. Save it with the creation path, original parameters and task ID.

Retry with the same API key, path, parameters and idempotency key:

curl "$BASE_URL/v1/videos" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: YOUR_RETURNED_KEY" \
  -d '{"model":"grok-imagine-video","prompt":"A cinematic sunset by the sea","duration":5}'

Completed replays return X-Idempotency-Replayed: true and reuse the original result without another generation or charge. A conflicting payload returns 409; an in-progress or unresolved submission can also return 409, so read the error rather than changing the key.

Creation timeouts, disconnects, 408 or 5xx can leave upstream acceptance unknown. The gateway does not create another task on a different provider in this case. Poll an existing task ID or contact operations with the original key and request ID. If the first connection fails before any response arrives, you may not receive the generated key: reliable automatic clients should generate and persist their own unique key before the first POST. Do not generate a new key on each retry. Current replay/task records are retained for 7 days, not indefinitely.

Legacy passthrough channels may retain task_id / request_id and older cache bindings. Explicit adapters provide persistent task binding; administrators should use a specific protocol for new channels. See Video Channels and Monitoring.

Poll and download

Poll GET /v1/videos/{id} with the same Bearer key. Explicit adapters normalize states to queued, in_progress, completed and failed; legacy channels can retain running / processing or other upstream values. Treat failed, cancelled and expired as terminal and read error when present.

Poll every 3–10 seconds with backoff and a bounded total wait, for example 10 minutes. Generation time depends on the model and queue. Retry a failed GET as a GET, never as a new creation POST. Explicit-adapter queries remain bound to the original provider. Download GET /v1/videos/{id}/content after completion:

curl "$BASE_URL/v1/videos/TASK_ID" -H "Authorization: Bearer $API_KEY"
curl "$BASE_URL/v1/videos/TASK_ID/content" -H "Authorization: Bearer $API_KEY" --output result.mp4

The /content URL is protected. Opening it directly in a browser omits the Authorization header and returns API_KEY_REQUIRED; use curl or an ordinary HTTP client request, or the web page download button, which fetches the Blob with your key. Save completed videos promptly; cached content is retained for up to 24 hours.

Prefer the unified /content endpoint over provider-specific content_url fields. Download availability still depends on provider file retention. Never put your API key in a URL query parameter.

Troubleshooting

For unavailable channels, check the group, model, resolution, duration, real-person flag and reference counts. For JSON errors, use application/json rather than multipart. For unresolved POSTs, preserve the original idempotency key and contact operations instead of resubmitting under a new key.

Provide the timestamp, model, path, task ID, idempotency key, response X-Request-ID and safe error details. Do not disclose your full API key or sensitive reference URLs.