Video API

Grok Imagine video now supports up to 14 reference images on the 1.5 model, pinned keyframes, preset voice references, and optional silent output. The dedicated edit and extension routes use the classic video model. All three operations return a Conflux request ID for the same polling route.

Video operations are asynchronous. Start a generation, edit, or extension, save its request_id, then poll GET /v1/videos/{request_id} with the same Conflux API key until the status is terminal.

POST /v1/videos/generations
POST /v1/videos/edits
POST /v1/videos/extensions
GET  /v1/videos/{request_id}

Use image for Image-to-Video when the supplied image must be the opening frame. This mode supports1080p with xai/grok-imagine-video-1.5.

{
  "model": "xai/grok-imagine-video-1.5",
  "prompt": "The subject slowly turns toward the camera",
  "image": {
    "url": "https://example.com/first-frame.jpg"
  },
  "duration": 5,
  "resolution": "1080p"
}

The image object accepts a public HTTPS URL, a base64 image data URI in url, or an xAI Files API file_id owned by the selected connected account.

"image": { "url": "data:image/png;base64,..." }
"image": { "file_id": "file_..." }

Add last_frame to pin the ending frame. It accepts the same url or file_idforms as image, and may be used without image or a prompt. Requests with last_frame support 480p or 720p.

{
  "model": "xai/grok-imagine-video-1.5",
  "prompt": "Move smoothly between the two shots",
  "image": { "url": "https://example.com/first-frame.jpg" },
  "last_frame": { "url": "https://example.com/last-frame.jpg" },
  "duration": 5,
  "resolution": "720p"
}

Use reference_images when images guide character, object, clothing, or scene consistency without becoming the opening frame. Reference-to-Video accepts up to 14 images onxai/grok-imagine-video-1.5, or up to seven on xai/grok-imagine-video. Both are limited to 720p.

{
  "model": "xai/grok-imagine-video-1.5",
  "prompt": "Keep the same character and outfit across the shot",
  "reference_images": [
    { "url": "https://example.com/front.jpg" },
    { "file_id": "file_profile" }
  ],
  "duration": 5,
  "resolution": "720p"
}

On xai/grok-imagine-video-1.5, use up to four keyframes to pin images inside the clip. Each entry has an image with the same HTTPS URL, image data URI, or xAIfile_id form as the first frame, plus a timestamp_s in seconds. The opening and ending frames use image and last_frame separately.

{
  "model": "xai/grok-imagine-video-1.5",
  "image": { "url": "https://example.com/opening.png" },
  "keyframes": [
    { "image": { "url": "https://example.com/middle.png" }, "timestamp_s": 2.1 },
    { "image": { "file_id": "file_next_scene" }, "timestamp_s": 4.0 }
  ],
  "last_frame": { "url": "https://example.com/ending.png" },
  "duration": 8,
  "resolution": "720p"
}

Every timestamp must be greater than zero and less than the clip duration, which defaults to 8 seconds. xAI snaps anchors to 1/3-second slots; timestamps need not be exact multiples or supplied in time order, but two anchors cannot land in the same snapped slot.

For preset voices, pass up to three reference_audios entries with a voice_id and refer to them as <AUDIO_0>, <AUDIO_1>, and<AUDIO_2> in the prompt. A voice-only request needs a prompt. Custom voice files are available from xAI only to trusted partners on request; this route documents preset voice IDs.

{
  "model": "xai/grok-imagine-video-1.5",
  "prompt": "The person from <IMAGE_0> speaks with the voice from <AUDIO_0>.",
  "reference_images": [{ "url": "https://example.com/speaker.jpg" }],
  "reference_audios": [{ "voice_id": "eve" }],
  "generate_audio": true,
  "duration": 8,
  "resolution": "720p"
}

Generated videos include audio by default. Set generate_audio to false to request a silent video.

Send an MP4 source and a prompt to POST /v1/videos/edits. Usexai/grok-imagine-video; the 1.5 model is not valid for edits. The source may be a public HTTPS URL, a base64 video data URI in url, or an xAI file_id owned by the connected account. The video object accepts exactly one of url or file_id.

POST /v1/videos/edits
{
  "model": "xai/grok-imagine-video",
  "prompt": "Change the coat to red while keeping the scene unchanged.",
  "video": { "url": "https://example.com/source.mp4" }
}

"video": { "url": "data:video/mp4;base64,..." }
"video": { "file_id": "file_source_video" }

An edit accepts a source up to 8.7 seconds. Its output keeps the source duration and aspect ratio, and keeps its resolution up to a 720p cap. Do not send custom duration,aspect_ratio, or resolution. Conflux checks the request shape; xAI validates the actual source codec, length, and dimensions.

Send an MP4 source and a prompt to POST /v1/videos/extensions withxai/grok-imagine-video. The same public HTTPS URL, base64 video data URI, or xAIfile_id source forms are supported.

POST /v1/videos/extensions
{
  "model": "xai/grok-imagine-video",
  "prompt": "The camera follows the cat as it jumps from the windowsill.",
  "video": { "file_id": "file_source_video" },
  "duration": 5
}

The source must be 2 to 15 seconds. duration adds 2 to 10 seconds and defaults to 6; the result contains the original clip plus the extension. A 10-second source withduration: 5 produces about 15 seconds of video. The output keeps the source aspect ratio and resolution up to 720p. Do not send custom aspect_ratio or resolution. Conflux checks the request shape; xAI validates the actual source codec, length, and dimensions.

The start response contains an owner-bound Conflux request ID.

{
  "request_id": "cfxvid_..."
}

curl "https://api.yoiyoi.xyz/v1/videos/$REQUEST_ID" \
  -H "Authorization: Bearer $CONFLUX_API_KEY"

$result = Invoke-RestMethod -Uri "https://api.yoiyoi.xyz/v1/videos/$($job.request_id)" -Headers $headers

$result.status
$result.video

Poll for up to 24 hours with the same workspace API key that started the request. Conflux binds thecfxvid_ ID to that workspace, key, and user; a different key receives 404. Results contain a temporary video.url. The API returns the URL and metadata, not the video file contents. For API-key video start requests, upstream HTTP 400 and 422 errors preserve their status and return a safe classified error code and redacted public message, not raw provider JSON.

• model is required. Generation supports xai/grok-imagine-video-1.5 and xai/grok-imagine-video; edits and extensions require the classic xai/grok-imagine-video model.
• prompt is required for Text-to-Video and voice-only generation, and for edits and extensions. It is optional when image, last_frame, reference_images, or keyframes is present. Supplied prompts are checked by the workspace compliance policy.
• image accepts exactly one url or file_id. HTTPS URLs, JPEG/PNG/WebP base64 data URIs, and xAI file IDs are supported.
• last_frame accepts the same input forms as image on the 1.5 model and caps resolution at 720p.
• reference_images accepts 1 to 14 image objects on 1.5 or 1 to 7 on classic. Classic cannot combine them with image.
• keyframes accepts up to four interior image/time pairs on 1.5. reference_audios accepts up to three preset voice_id objects on 1.5.
• generate_audio is a boolean. Audio is included by default; set it to false for silent output.
• Generation duration must be an integer from 1 to 15 seconds and defaults to 8. Classic Reference-to-Video with reference_images is capped at 10 seconds. Extension duration is the added 2 to 10 seconds and defaults to 6.
• aspect_ratio supports 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, and 2:3.
• resolution supports 480p, 720p, and native 1080p for 1.5 Text-to-Video and Image-to-Video. Requests with last_frame, keyframes, reference_images, or reference_audios, and all classic generation, are capped at 720p.
• Generation, edit, and extension requests reject unsupported top-level n, size, quality, seed, and response_format with HTTP 400.