中文文档
API Console

模型能力

参考图转视频

查看 Markdown
创建 API Key 试用 Playground了解 Grok 4.7

提供参考图像、预设语音，或同时提供两者来引导视频生成。图像可以将特定人物、物体、服装或其他视觉元素融入视频，同时不会锁定首帧（不同于 图像转视频）。这适用于虚拟试穿、产品植入、角色一致的叙事以及语音身份。在 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。

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_1> 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_2> 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 传入最多 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 xai_sdk

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

response = client.video.generate(
    prompt="The person from <IMAGE_1> presents the product from <IMAGE_2> on the set from <IMAGE_3>, 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，格式同 图像转视频 相同。Python SDK 和 Vercel AI SDK 尚未提供专用的 last_frame 参数，请在 REST 请求体中发送。

经典版 grok-imagine-video 会拒绝 last_frame，也不允许将 image 与参考输入组合使用。

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"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

关键帧

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

JSON

"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。首尾请使用 image / last_frame。
间隔锚点按 1/3 秒网格对齐。两个关键帧若舍入到同一格会被拒绝，因此至少应间隔 1/3 秒。
输入每个 image 都接受相同的 URL、data-URI 和 file_id，格式同 图像转视频。

Python SDK 和 Vercel AI SDK 尚未提供专用的 keyframes 参数；请在 REST 请求体中发送。经典版 grok-imagine-video 会拒绝 keyframes，且关键帧不能与视频编辑结合使用。

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": "A slow tracking shot through the workshop: the sketch on the bench becomes a clay model, then the finished bronze in the window.",
        "image": {"url": "<FIRST_FRAME_URL>"},
        "keyframes": [
            {"image": {"url": "<KEYFRAME_URL_1>"}, "timestamp_s": 3.0},
            {"image": {"url": "<KEYFRAME_URL_2>"}, "timestamp_s": 6.0},
        ],
        "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"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

最后更新：2026 年 9 月 21 日