提供参考图像、预设语音，或同时提供两者来引导视频生成。图像可以将特定人物、物体、服装或其他视觉元素融入视频，同时不会锁定首帧（不同于图像转视频）。适用于虚拟试穿、产品植入和含有重复出场角色的故事。在 grok-imagine-video-1.5 上，你还可以选择主体说话时使用的语音（参见参考音频）、固定精确的首帧或尾帧（见首帧与尾帧），以及在片段内部的指定时刻固定帧（见关键帧）。

每张参考图像都可以通过公开 HTTPS URL、Base64 编码的数据 URI 或 file_id（来自 Files API）提供，也可以在一次请求中混用这些类型。详见 Imagine → Files API 集成，了解 file_id 的详细信息和示例。

在 Vercel AI SDK 中，将 providerOptions.xai.mode 设置为 "reference-to-video"，并通过 providerOptions.xai.referenceImageUrls。

使用多张参考图时，给每张图分配一种用途，并明确其元素在场景中的位置。尽量减少出场角色，并保持道具静止。

限制	取值
参考图像	最多 14，按每次请求计算，适用于 `grok-imagine-video-1.5`；最多 7，适用于 `grok-imagine-video`
参考声音	最多 3，按每次请求计算，适用于 `grok-imagine-video-1.5`，用以下字段指定预设声音：`voice_id`（见参考音频）
指定帧	`grok-imagine-video-1.5` 专属：使用 `image` 与参考输入一起指定首帧，可指定 `last_frame`，以及最多 4 `keyframes`（见首帧与尾帧和关键帧）
必需输入	至少提供一张参考图像、一个声音、一个 `last_frame` 或 `keyframes` 条目
时长	最多 15 秒，适用于 `grok-imagine-video-1.5`；最多 10 秒，适用于 `grok-imagine-video`
分辨率	最多 720p

在提示词中按列表位置引用参考图像。第一张从 <IMAGE_0> 开始，下一张为 <IMAGE_1>，以此类推。如果还设置了 image 来指定首帧，它会占用 <IMAGE_0>，参考图像则从以下编号起算：<IMAGE_1>。

import { xai } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
    model: xai.video("grok-imagine-video-1.5"),
    prompt: "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_0> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_1> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: {
            mode: "reference-to-video",
            referenceImageUrls: [
                "<IMAGE_URL_1>",
                "<IMAGE_URL_2>",
                "<IMAGE_URL_3>",
            ],
            resolution: "720p",
            pollTimeoutMs: 600000,
        },
    },
});

const videoUrl = result.providerMetadata?.xai?.videoUrl;
console.log(videoUrl);

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_0> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_1> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
        "reference_images": [
            {"url": "<IMAGE_URL_1>"},
            {"url": "<IMAGE_URL_2>"},
            {"url": "<IMAGE_URL_3>"},
        ],
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    time.sleep(5)

# Start the reference-to-video request
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_0> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_1> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    "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')

# Poll until the video is ready
while true; do
  RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \
    -H "Authorization: Bearer $XAI_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    echo "$RESULT" | jq -r '.video.url'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

import os
import xai_sdk

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

response = client.video.generate(
    prompt="slow zoom in on the white fashion runway stage. then, the model from <IMAGE_0> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_1> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    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)

参考音频

对于 grok-imagine-video-1.5，你可以为主体指定声音。最多支持 3 个预设声音，通过以下字段传入：reference_audios。每个条目通过 voice_id 指定语音；这些语音来自与 Text to Speech 相同的内置列表，因此 {"voice_id": "eve"} 会使用 Eve 的语音说话。标识符不区分大小写；未知标识符会返回 400，并列出可用声音。所有声音都可试听，见旗舰语音公告。

reference_audios 接受预设声音。受信任的合作伙伴若需使用自己的音频文件作为参考，可申请开通。语音可以与参考图像一起使用，也可以单独使用；在 prompt 中使用 <AUDIO_0>，<AUDIO_1> 和 <AUDIO_2> 标记语音（如果还传入图像，则使用 <IMAGE_0>……）。

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "The person from <IMAGE_0> presents the product from <IMAGE_1> on the set from <IMAGE_2>, speaking with the voice from <AUDIO_0>. A second speaker with the voice from <AUDIO_1> replies.",
        "reference_images": [
            {"url": "<IMAGE_URL_1>"},
            {"url": "<IMAGE_URL_2>"},
            {"url": "<IMAGE_URL_3>"},
        ],
        "reference_audios": [
            {"voice_id": "eve"},
            {"voice_id": "leo"},
        ],
        "duration": 8,
        "aspect_ratio": "9:16",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    time.sleep(5)

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": "The person from <IMAGE_0> presents the product from <IMAGE_1> on the set from <IMAGE_2>, speaking with the voice from <AUDIO_0>. A second speaker with the voice from <AUDIO_1> replies.",
    "reference_images": [
      {"url": "<IMAGE_URL_1>"},
      {"url": "<IMAGE_URL_2>"},
      {"url": "<IMAGE_URL_3>"}
    ],
    "reference_audios": [
      {"voice_id": "eve"},
      {"voice_id": "leo"}
    ],
    "duration": 8,
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }' | jq -r '.request_id')

while true; do
  RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \
    -H "Authorization: Bearer $XAI_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    echo "$RESULT" | jq -r '.video.url'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

import os
import xai_sdk

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

response = client.video.generate(
    prompt="The person from <IMAGE_0> presents the product from <IMAGE_1> on the set from <IMAGE_2>, speaking with the voice from <AUDIO_0>. A second speaker with the voice from <AUDIO_1> replies.",
    model="grok-imagine-video-1.5",
    reference_image_urls=[
        "<IMAGE_URL_1>",
        "<IMAGE_URL_2>",
        "<IMAGE_URL_3>",
    ],
    reference_audios=[
        {"voice_id": "eve"},
        {"voice_id": "leo"},
    ],
    duration=8,
    aspect_ratio="9:16",
    resolution="720p",
)

print(response.url)

首帧与尾帧

对于 grok-imagine-video-1.5，last_frame 会固定视频精确的尾帧。视频结束时会到达该图像，而非将它作为参考重新渲染。image 配合 reference_images，reference_audios 或 last_frame 使用时，则会相应地固定首帧。

请求结构	结果
`image` + `last_frame`	固定首帧和尾帧。模型在两者之间插值。
`last_frame`（仅此一项）	固定尾帧。模型生成开场，并最终到达固定的图像。
`last_frame` + `reference_images` / `reference_audios`	在参考输入引导下固定尾帧。添加 `image` 还可同时固定首帧。

prompt 在所有首尾帧请求中均为可选参数。提供它可引导帧间的运动和镜头；省略时则仅由帧决定视频内容。

last_frame 支持 URL、data URI 和 file_id，格式同图像转视频。各 SDK 指定帧的方式如下：

指定帧	REST	Python SDK	Vercel AI SDK
首帧	`image`	`image_url` 或 `image_file_id`	`frameImages` 条目，并设置 `frameType: "first_frame"`
末帧	`last_frame`	`last_frame_url` 或 `last_frame_file_id`	`frameImages` 条目，并设置 `frameType: "last_frame"`

Vercel AI SDK 的这些选项需要 @ai-sdk/xai 5.0.8 或更高版本。

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "The camera dollies from the sunlit doorway to the window, settling on the closing frame.",
        "image": {"url": "<FIRST_FRAME_URL>"},
        "last_frame": {"url": "<LAST_FRAME_URL>"},
        "duration": 8,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    time.sleep(5)

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": "The camera dollies from the sunlit doorway to the window, settling on the closing frame.",
    "image": {"url": "<FIRST_FRAME_URL>"},
    "last_frame": {"url": "<LAST_FRAME_URL>"},
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' | jq -r '.request_id')

while true; do
  RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \
    -H "Authorization: Bearer $XAI_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    echo "$RESULT" | jq -r '.video.url'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

import os
import xai_sdk

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

response = client.video.generate(
    prompt="The camera dollies from the sunlit doorway to the window, settling on the closing frame.",
    model="grok-imagine-video-1.5",
    image_url="<FIRST_FRAME_URL>",
    last_frame_url="<LAST_FRAME_URL>",
    duration=8,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

关键帧

对于 grok-imagine-video-1.5，keyframes 可在片段内部的指定时刻固定图像。每个条目将 image 与 timestamp_s 配对，视频会在该时刻呈现这张确切的图像。可用它为镜头设计分镜：模型在锚点之间生成运动，而不是从单帧构想整个片段。

"keyframes": [
  {"image": {"url": "<KEYFRAME_URL_1>"}, "timestamp_s": 2.0},
  {"image": {"url": "<KEYFRAME_URL_2>"}, "timestamp_s": 4.0}
]

关键帧用于片段内部，首尾仍使用各自的字段。使用 image 固定开头，使用 last_frame 固定结尾；三者均可与 reference_images 或 reference_audios 结合使用。prompt 在固定任意一帧时都是可选的。

约束	详情
数量	每个请求最多 4 个关键帧。
时间	`timestamp_s` 必须严格位于片段内部：大于 0 且小于 `duration`。
间隔	锚点按 1/3 秒网格对齐。两个关键帧若舍入到同一格会被拒绝，因此至少应间隔 1/3 秒。
输入	每个 `image` 都接受相同的 URL、data-URI 和 `file_id`，格式同图像转视频。

各 SDK 的关键帧字段名称有所不同：

字段	REST	Python SDK	Vercel AI SDK
列表	`keyframes`	`keyframes`	`providerOptions.xai.keyframes`
图像	`image` 对象	`image_url` 或 `image_file_id`	`imageUrl`
时间（秒）	`timestamp_s`	`timestamp`	`timestampSeconds`
首尾帧	`image`，`last_frame`	`image_url`，`last_frame_url`	`frameImages`

例如，Python SDK 中的一个条目为 {"image_url": "<KEYFRAME_URL_1>", "timestamp": 2.0}。Vercel AI SDK 的这些选项需要 @ai-sdk/xai 5.0.8 或更高版本。

示例：循环播放四季更替

指定帧来自同一场景时效果最佳。先生成一张静态图像，再通过图像编辑制作其余画面，只改动需要变化的部分。要循环播放视频，请将同一张图像同时用作image和last_frame。

视频生成：根据文本提示词生成视频
图像转视频：让静态图像动起来
视频编辑：编辑现有视频
API 参考：完整的端点文档
Imagine API 主页：展示 Imagine API 的实际效果

最后更新：2026 年 10 月 19 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

模型能力

参考图转视频

参考音频

首帧与尾帧

关键帧

示例：循环播放四季更替

参考音频

首帧与尾帧

关键帧

示例：循环播放四季更替

相关内容