使用 Grok 视频模型根据文本 prompt 生成视频。API 支持配置 duration、aspect ratio 和 resolution，SDK 会自动处理异步 polling。在 grok-imagine-video-1.5 上，text-to-video 支持原生 1080p。

快速开始

通过一次 API 调用生成视频：

import os
import xai_sdk

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

response = client.video.generate(
    prompt="A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    model="grok-imagine-video-1.5",
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

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 glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

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

# Poll until the video is ready
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)

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: "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: { resolution: "720p" },
    },
});

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

# Start the video generation 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": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    "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" ] || [ "$STATUS" = "expired" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

视频生成是一个异步过程，通常最多需要几分钟才能完成。具体耗时取决于：

Prompt 复杂度 — 场景越详细，需要的处理越多
Duration — 视频越长，生成时间越长
Resolution — resolution 越高（1080p 相比 480p），处理时间越长
视频编辑 — 与 image-to-video 或 text-to-video 相比，编辑现有视频会增加额外开销

视频工作流

请根据希望创建的视频输出类型选择对应页面：

Image-to-Video — 让静态图像动起来。
视频编辑 — 修改现有视频。
Reference-to-Video — 使用一张或多张参考图像引导视频生成。
视频扩展 — 从现有视频的最后一帧继续生成。

工作原理

在底层，视频生成分为两个步骤：

启动 — 提交生成请求并接收 request_id
Poll — 使用 request_id 反复检查 status，直到视频就绪

xAI SDK 的 generate() 和 extend() 方法完全封装了这一过程；它们会提交请求、poll 结果并返回已完成的视频 response。你无需管理 request ID 或实现 polling 逻辑。对于长时间运行的生成任务，你可以自定义 polling 行为，设置 timeout 和 interval 参数；也可以手动处理 polling，从而完全控制生成生命周期。

REST API 用户必须手动实现这一两步流程：

第 1 步：启动生成请求

curl -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": "A glowing crystal-powered rocket launching from Mars"
  }'

Response：

{"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"}

第 2 步：Poll 结果

使用 request_id 检查 status。每隔几秒继续 polling，直到视频就绪：

curl -X GET "https://api.x.ai/v1/videos/{request_id}" \
  -H "Authorization: Bearer $XAI_API_KEY"

Response 包含一个 status 字段，其值为以下之一：

Status	说明
`pending`	视频仍在生成
`done`	视频已就绪
`expired`	请求已过期
`failed`	视频生成失败

Response（完成时）：

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/.../video.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "model": "grok-imagine-video-1.5"
}

视频以临时 URL 形式返回。需要时可以直接访问 xAI 托管的 URL；如果需要保留副本，请及时下载或处理。

配置

视频生成 API 允许你控制生成视频的输出格式。你可以指定 duration、aspect ratio、resolution，以及（在 reference-to-video 中）preset voice，以满足具体用例。

Duration

使用 duration 参数控制视频长度。允许范围为 1–15 秒。

视频编辑不支持自定义 duration。编辑后的视频会保留原视频时长，上限为 8.7 秒。

Aspect Ratio

Ratio	用例
`1:1`	社交媒体、缩略图
`16:9` / `9:16`	宽屏、移动端、Stories（默认：`16:9`）
`4:3` / `3:4`	演示文稿、人像
`3:2` / `2:3`	摄影

对于 image-to-video 生成，输出默认采用输入图像的 aspect ratio。如果指定 aspect_ratio 参数，则会覆盖默认值，并将图像拉伸到所需的 aspect ratio。

视频编辑不支持自定义 aspect_ratio — 输出会匹配输入视频的 aspect ratio。

Resolution

Resolution	说明
`1080p`	Full HD 画质
`720p`	HD 画质
`480p`	标准清晰度，处理更快（默认）

注意： 1080p 在 grok-imagine-video-1.5 上支持 text-to-video 和 image-to-video。Reference-to-video 最高为 720p。

视频编辑不支持自定义 resolution。输出 resolution 会匹配输入视频的 resolution，最高为 720p（例如，1080p 输入会缩小到 720p）。

音频

在 grok-imagine-video-1.5 上，reference-to-video 可以通过 reference_audios 携带 voice。voice 来自内置列表，并通过 voice_id 命名；你不能上传自己的音频 clip：

属性	说明
来源	一个 preset `voice_id`（例如 `{"voice_id": "eve"}`），来自与 Text to Speech 相同的列表。标识符不区分大小写
限制	每次请求最多 3 个 voice
Prompt	按索引引用 voice：`<AUDIO_0>` 上，`<AUDIO_1>` 上，`<AUDIO_2>`

生成的视频默认包含音轨。

示例

import os
import xai_sdk

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

response = client.video.generate(
    prompt="Timelapse of a flower blooming in a sunlit garden",
    model="grok-imagine-video-1.5",
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(f"Video URL: {response.url}")
print(f"Duration: {response.duration}s")

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": "Timelapse of a flower blooming in a sunlit garden",
        "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(f"Video URL: {data['video']['url']}")
        print(f"Duration: {data['video']['duration']}s")
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

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: "Timelapse of a flower blooming in a sunlit garden",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: { resolution: "720p" },
    },
});

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

# Start the video generation 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": "Timelapse of a flower blooming in a sunlit garden",
    "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" ] || [ "$STATUS" = "expired" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

请求模式

视频生成 endpoint 支持多种模式，具体模式由设置的字段决定。每次请求只能激活一种模式：

模式	REST API 字段	AI SDK 结构	说明
Text-to-video	`prompt` only	`prompt: "..."`	仅根据文本 prompt 生成视频。
Image-to-video	`prompt` + `image`	`prompt: { image, text }`	使用提供的图像作为起始帧生成视频。
Reference-to-video	`prompt` + `reference_images` 或 `reference_audios`	`prompt: "..."` + `providerOptions.xai.{ mode: "reference-to-video", referenceImageUrls }`	在 `grok-imagine-video-1.5` 上，根据参考图像和/或 preset voice 引导视频生成。
Edit-video	`/v1/videos/edits` + `video`	`prompt: "..."` + `providerOptions.xai.{ mode: "edit-video", videoUrl }`	根据 prompt 修改现有视频。
Extend-video	`/v1/videos/extensions` + `video`	`prompt: "..."` + `providerOptions.xai.{ mode: "extend-video", videoUrl }`	从现有视频的最后一帧进行扩展。

以下组合不允许使用，并会返回 400 Bad Request 错误：

image + reference_images — 二者只能选其一
在 AI SDK 中混用 mode 值 — 每次请求只支持 "edit-video" 上，"extend-video"、"reference-to-video"

省略 mode 时，AI SDK 会使用标准生成模式。

自定义 Polling 行为

使用 SDK 的 generate() 或 extend() 方法时，可以控制等待时长和结果检查频率：

Python SDK	AI SDK（`providerOptions.xai`）	说明	默认值
`timeout`	`pollTimeoutMs`	等待视频完成的最长时间	10 分钟
`interval`	`pollIntervalMs`	status 检查间隔	100 毫秒

import os
from datetime import timedelta
import xai_sdk

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

response = client.video.generate(
    prompt="Epic cinematic drone shot flying through mountain peaks",
    model="grok-imagine-video-1.5",
    duration=15,
    timeout=timedelta(minutes=15),  # Wait up to 15 minutes
    interval=timedelta(seconds=5),  # Check every 5 seconds
)

print(response.url)

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: "Epic cinematic drone shot flying through mountain peaks",
    duration: 15,
    providerOptions: {
        xai: {
            pollTimeoutMs: 15 * 60 * 1000,  // Wait up to 15 minutes
            pollIntervalMs: 5 * 1000,        // Check every 5 seconds
        },
    },
});

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

如果视频在 timeout 期限内仍未就绪，Python SDK 会抛出 TimeoutError，AI SDK 则会通过其 AbortSignal 中止。如需更精细的控制，请使用手动 polling 方式；Python SDK 提供 start() 和 get() 方法，AI SDK 则支持自定义 abortSignal 来取消操作。

手动处理 Polling

如需精细控制生成生命周期，请分别使用 start() 或 extend_start() 发起生成/扩展请求，并使用 get() 检查 status。

该 get() 方法会返回包含 status 字段的 response。请从 SDK 导入 status enum：

import os
import time
import xai_sdk
from xai_sdk.proto import deferred_pb2

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

# Start the generation request
start_response = client.video.start(
    prompt="A cat lounging in a sunbeam, tail gently swishing",
    model="grok-imagine-video-1.5",
    duration=5,
)

print(f"Request ID: {start_response.request_id}")

# Poll for results
while True:
    result = client.video.get(start_response.request_id)
    
    if result.status == deferred_pb2.DeferredStatus.DONE:
        print(f"Video URL: {result.response.video.url}")
        break
    elif result.status == deferred_pb2.DeferredStatus.EXPIRED:
        print("Request expired")
        break
    elif result.status == deferred_pb2.DeferredStatus.FAILED:
        print("Video generation failed")
        break
    elif result.status == deferred_pb2.DeferredStatus.PENDING:
        print("Still processing...")
        time.sleep(5)

import os
import time
import requests

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

# Step 1: Start generation
response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "A cat lounging in a sunbeam, tail gently swishing",
        "duration": 5,
    },
)

request_id = response.json()["request_id"]
print(f"Request ID: {request_id}")

# Step 2: Poll for results
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(f"Video URL: {data['video']['url']}")
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    else:
        print("Still processing...")
        time.sleep(5)

// Step 1: Start generation
const response = await fetch("https://api.x.ai/v1/videos/generations", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    },
    body: JSON.stringify({
        model: "grok-imagine-video-1.5",
        prompt: "A cat lounging in a sunbeam, tail gently swishing",
        duration: 5,
    }),
});

const { request_id } = await response.json();
console.log(`Request ID: ${request_id}`);

// Step 2: Poll for results
while (true) {
    const result = await fetch(`https://api.x.ai/v1/videos/${request_id}`, {
        headers: { "Authorization": `Bearer ${process.env.XAI_API_KEY}` },
    });

    const data = await result.json();

    if (data.status === "done") {
        console.log(`Video URL: ${data.video.url}`);
        break;
    } else if (data.status === "expired") {
        console.log("Request expired");
        break;
    } else if (data.status === "failed") {
        console.log("Video generation failed");
        break;
    } else {
        console.log("Still processing...");
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

# Step 1: Start generation
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": "A cat lounging in a sunbeam, tail gently swishing",
    "duration": 5
  }' | jq -r '.request_id')

echo "Request ID: $REQUEST_ID"

# Step 2: Poll for results
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" ] || [ "$STATUS" = "expired" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  echo "Still processing..."
  sleep 5
done

可用的 status 值如下：

Proto 值	说明
`deferred_pb2.DeferredStatus.PENDING`	视频仍在生成
`deferred_pb2.DeferredStatus.DONE`	视频已就绪
`deferred_pb2.DeferredStatus.EXPIRED`	请求已过期
`deferred_pb2.DeferredStatus.FAILED`	视频生成失败

错误处理

使用 SDK 的 generate() 或 extend() 方法时，视频生成失败会以 VideoGenerationError exception 形式抛出。该 exception 包含 code 和 message，用于说明错误原因。请从 xai_sdk.video 导入：

import os
import xai_sdk
from xai_sdk.video import VideoGenerationError

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

try:
    response = client.video.generate(
        prompt="A cat lounging in a sunbeam, tail gently swishing",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(response.url)
except VideoGenerationError as e:
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")

该 VideoGenerationError exception 具有以下属性：

属性	类型	说明
`code`	`str`	用于标识失败原因的错误代码
`message`	`str`	描述失败原因的可读消息

手动 polling 时，生成失败会返回 status: "failed"，其中包含 error 对象：

{
  "status": "failed",
  "error": {
    "code": "invalid_argument",
    "message": "Prompt cannot be empty. Please provide a prompt."
  }
}

可能的 error.code 值如下：

代码	含义	处理方式
`invalid_argument`	请求输入无效，例如不支持的 duration、无效的图像或视频输入、过长的 prompt、冲突的请求模式，或内容被 moderation 阻止。	修正请求参数或输入媒体，然后提交新请求。
`permission_denied`	API key 或 team 没有执行所请求视频操作的权限。	确认 API key 属于正确的 team，并且该 team 有权访问所请求的能力。
`failed_precondition`	所选 model 或设置不支持请求的操作，例如视频编辑、视频扩展，或 model 无法处理所请求的 resolution。	更改 model、mode、resolution 或其他请求设置。
`service_unavailable`	视频生成服务暂时过载。	稍后重试请求。
`internal_error`	服务因内部故障无法完成生成。	重试请求。如果错误仍然存在，请携带 `request_id` 上，根据参考图像和/或 preset voice 引导视频生成。

身份验证错误、model 不存在和 rate limit 会在创建视频 job 之前作为标准 API 错误同步返回，因此不会出现在失败视频结果的 error.code 字段中。

你可以将其与 TimeoutError 处理结合使用，以全面覆盖错误：

import os
import xai_sdk
from xai_sdk.video import VideoGenerationError

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

try:
    response = client.video.generate(
        prompt="A cat lounging in a sunbeam, tail gently swishing",
        model="grok-imagine-video-1.5",
        duration=5,
    )
    print(response.url)
except VideoGenerationError as e:
    print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
    print("Generation timed out — try increasing the timeout or simplifying the prompt")

Response 详情

SDK response 包含生成的视频和 provider-specific metadata。在 AI SDK 中，xAI 托管的输出 URL 位于 providerMetadata.xai.videoUrl 上，根据参考图像和/或 preset voice 引导视频生成。

if response.respect_moderation:
    print(response.url)
else:
    print("Video filtered by moderation")

print(f"Duration: {response.duration} seconds")
print(f"Model: {response.model}")

const result = await generateVideo({
    model: xai.video("grok-imagine-video-1.5"),
    prompt: "A futuristic city skyline at dusk",
    duration: 5,
});

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

并发请求

需要生成多个视频时，请并发运行请求。这对于比较 prompt 或创建多个变体尤其有用。

import os
import asyncio
import xai_sdk

async def generate_concurrently():
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))

    prompts = [
        "A cat sitting on a sunlit windowsill, tail gently swishing.",
        "A dog sprinting through a field of tall grass at golden hour.",
        "A hummingbird hovering near a red flower in slow motion.",
    ]

    tasks = [
        client.video.generate(
            prompt=prompt,
            model="grok-imagine-video-1.5",
            duration=5,
        )
        for prompt in prompts
    ]

    results = await asyncio.gather(*tasks)

    for prompt, result in zip(prompts, results):
        print(f"{prompt}: {result.url}")

asyncio.run(generate_concurrently())

Models — 可用的视频 model 与价格
Image-to-Video — 让静态图像动起来
Reference-to-Video — 使用参考图像引导视频生成
视频编辑 — 编辑现有视频
视频扩展 — 扩展现有视频
图像生成 — 根据文本生成静态图像
API 参考 — 完整的 endpoint 文档
Imagine API 主页 — 查看 Imagine API 的实际效果