Generate a video from reference images

On grok-imagine-video-1.5, POST https://api.x.ai/v1/videos/generations takes reference_images so a person, product, or outfit can show up in the clip. Tag them in the prompt as <IMAGE_1>, <IMAGE_2>, <IMAGE_3>. The stills steer the scene. The first frame is generated from the prompt.

Each reference can be a public HTTPS URL, a data URI, or a Files API file_id. Mix kinds in one request. Video jobs are async: poll GET /v1/videos/{request_id} until status is done.

Runway from three stills

REQUEST_ID=$(curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening. they wear the shirt from <IMAGE_2>. they look at the camera.",
    "reference_images": [
      {"url": "<IMAGE_URL_1>"},
      {"url": "<IMAGE_URL_2>"},
      {"url": "<IMAGE_URL_3>"}
    ],
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' | jq -r '.request_id')

Python SDK:

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="the model from <IMAGE_1> walks the runway in the shirt from <IMAGE_2>",
    model="grok-imagine-video-1.5",
    reference_image_urls=["<IMAGE_URL_1>", "<IMAGE_URL_2>", "<IMAGE_URL_3>"],
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)
print(response.url)

On grok-imagine-video-1.5 you can also pass up to three preset voices with reference_audios: [{"voice_id": "eve"}]. Tag them as <AUDIO_0>, <AUDIO_1>. Identifiers are case-insensitive. An unknown voice_id returns 400 with the available list. Your own audio files as voice references are partner-only.

In the Vercel AI SDK, set providerOptions.xai.mode to "reference-to-video" and pass providerOptions.xai.referenceImageUrls.

Pitfalls

• Image-to-video uses image as the opening frame. This path uses reference_images.
• Preset voices are generally available. Custom audio references need a partner grant.
• Default video URLs expire. Persist with storage_options if you need the file later.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.