Videos

Start a video generation

Queues a video generation and returns 202 with the job. Poll GET /api/v1/video-generations/{id} until state is succeeded, failed, blocked or cancelled. On success, output.availability says whether the clip can be downloaded: ready means output.url is a signed download URL valid for 15 minutes (re-fetch the job for a fresh one); pending_scan means the saved file is still being scanned, so keep re-fetching the job (self-hosted installs can stay here for up to ~30 minutes); unavailable means the file was blocked or deleted and output.url will never be set, so stop polling. Credits for the requested duration are reserved up front and settled on completion; a failed or cancelled job is not charged. A blocked job is not charged either, unless the provider generated the clip before rejecting it and billed it: then the requested duration is charged and credits.settled shows it. Send an Idempotency-Key header (1-255 printable ASCII characters) to make retries safe: a repeat with the same key and body returns the original job, and the same key with a different body is a 422 idempotency_key_reused. Omitted fields take the model defaults from GET /api/v1/video-models. Set organization_id to bill an organization you belong to, or null to bill your personal credits; omitted, the job bills your home organization (or your personal credits if you have none). Keys are scoped to the billed account, so the same key sent for a different organization_id starts a new job. An organization-billed API key always bills its own organization (see organization_id).

post/api/v1/video-generations

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/v1/video-generations
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

modelstring required

A model id from GET /api/v1/video-models.

promptstring required
mode'text_to_video' | 'image_to_video'

Defaults to image_to_video when input_image_file_id is set, else text_to_video.

duration_secondsnumber

Defaults to the model's default duration.

aspect_ratio'16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9'
resolution'360p' | '480p' | '720p' | '1080p' | '4k'
input_image_file_idstring

An image file you own, for image_to_video.

audioboolean
organization_idstring nullable

The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (errorCode: billing_organization_mismatch).

Example request

{
  "model": "grok-imagine-video-1.5",
  "prompt": "A slow dolly shot of a red lighthouse at dusk"
}

Response

Accepted; the job is queued (or replayed for a repeated Idempotency-Key).

idstring required
object'video_generation' required
state'pending' | 'running' | 'storing' | 'succeeded' | 'failed' | 'blocked' | 'cancelled' required
modelstring required
mode'text_to_video' | 'image_to_video' required
promptstring required
duration_secondsnumber required
aspect_ratio'16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9' required
resolution'360p' | '480p' | '720p' | '1080p' | '4k' required
source'api' | 'studio' | 'agent' required
progressnumber nullable required
created_atstring required
updated_atstring required

Example response

{
  "id": "664f1c2b9a1e4d0012ab34cd",
  "object": "video_generation",
  "state": "pending",
  "model": "grok-imagine-video-1.5",
  "mode": "text_to_video",
  "prompt": "A slow dolly shot of a red lighthouse at dusk",
  "duration_seconds": 6,
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "source": "api",
  "progress": null,
  "error": null,
  "output": null,
  "credits": {
    "reserved": 960,
    "settled": null
  },
  "created_at": "2026-10-06T00:00:00.000Z",
  "updated_at": "2026-10-06T00:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.