推理 API

视频

POST /v1/videos/generations

根据文本提示词和可选图像生成视频。这是一个异步操作，返回一个用于轮询的 request_id。

请求体

aspect_ratio ("1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3") — 视频宽高比
duration (integer | null) — 视频时长（秒）。范围：[1, 15]。默认值：8。也接受 seconds 以兼容 OpenAI API。同时接受数字（8）和字符串（"8"）值。
image (object)
- file_id (string | null) — 来自 xAI Files API 的文件 ID。与 url 互斥。文件必须是图像（JPEG、PNG 或 WebP）且已完全上传。
- url (string) — 图像的公共 URL 或 base64 编码的数据 URL（JPEG、PNG 或 WebP）。也接受 image_url 以兼容。当未设置 file_id 时必需。
model (string | null) — 要使用的模型。
output (object)
- upload_url (string, required) — 用于通过 HTTP PUT 上传生成视频的签名 URL。
prompt (string) — 视频生成的提示词。文本生成视频（T2V）和参考生成视频（R2V）必需。图像生成视频（I2V）可选 — 当省略时，模型仅从图像生成视频。
reference_audios (array<object>) — 参考生成视频（R2V）的可选参考音频（声音身份）。每个条目通过 voice_id 选择一个第一方预设声音。仅受部分视频模型支持；最多 3 个条目。可以不提供 reference_images（仅音频的参考生成视频）— 至少提供一种参考将选择参考生成视频模式。
- voice_id (string, required) — 第一方预设声音的标识符（例如 "ara"；与 TTS API 相同的声音标识符），在服务器端解析为模型声音预设目录中的精选参考片段。
reference_images (array<object>) — 参考生成视频（R2V）的可选参考图像。提供时，使用这些图像作为风格/内容参考生成视频。
- file_id (string | null) — 来自 xAI Files API 的文件 ID。与 url 互斥。文件必须是图像（JPEG、PNG 或 WebP）且已完全上传。
- url (string) — 图像的公共 URL 或 base64 编码的数据 URL（JPEG、PNG 或 WebP）。也接受 image_url 以兼容。当未设置 file_id 时必需。
resolution ("480p" | "720p" | "1080p") — 视频分辨率
storage_options (object)
- expires_after (integer | null) — 从现在起文件自动过期前的秒数。最大 2592000（30 天）。如果省略，文件永不过期。
- filename (string, required) — 存储文件的文件名。
- public_url (boolean | object)
user (string | null) — 代表终端用户的唯一标识符。

响应体

request_id (string, required) — 用于轮询结果的唯一请求 ID。

代码示例

bash

curl -s 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 serene lake at sunrise with mist rolling over the water"
  }'

javascript

const response = await fetch("https://api.x.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-imagine-video-1.5",
    prompt: "A serene lake at sunrise with mist rolling over the water",
  }),
});

console.log(JSON.stringify(await response.json(), null, 2));

python

import json
import os

import requests

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "A serene lake at sunrise with mist rolling over the water",
    },
)

print(json.dumps(response.json(), indent=2))

响应示例:

json

{
  "request_id": "a3d1008e-4544-40d4-d075-11527e794e4a"
}

POST /v1/videos/edits

根据提示词编辑视频。这是一个异步操作，返回一个用于轮询的 request_id。

请求体

model (string | null) — 要使用的模型。
output (object)
- upload_url (string, required) — 用于通过 HTTP PUT 上传生成视频的签名 URL。
prompt (string, required) — 视频编辑的提示词。
storage_options (object)
- expires_after (integer | null) — 从现在起文件自动过期前的秒数。最大 2592000（30 天）。如果省略，文件永不过期。
- filename (string, required) — 存储文件的文件名。
- public_url (boolean | object)
user (string | null) — 代表终端用户的唯一标识符。
video (object, required) — 编辑和扩展请求的视频输入。接受公共 URL、base64 编码的数据 URL 或来自 xAI Files API 的 file_id。
- file_id (string | null) — 来自 xAI Files API 的文件 ID。与 url 互斥。文件必须是视频（例如 MP4）且已完全上传。
- url (string) — 视频的 URL（公共 URL 或 base64 编码的数据 URL）。视频必须具有 .mp4 文件扩展名，并使用 .mp4 支持的编解码器（如 H.265、H.264、AV1 等）进行编码。当未设置 file_id 时必需。

响应体

request_id (string, required) — 用于轮询结果的唯一请求 ID。

代码示例

bash

curl -s https://api.x.ai/v1/videos/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d "{
    \"model\": \"grok-imagine-video\",
    \"prompt\": \"Give the woman a silver necklace\",
    \"video\": {
      \"url\": \"$VIDEO_URL\"
    }
  }"

javascript

const response = await fetch("https://api.x.ai/v1/videos/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-imagine-video",
    prompt: "Give the woman a silver necklace",
    video: {
      url: process.env.VIDEO_URL,
    },
  }),
});

console.log(JSON.stringify(await response.json(), null, 2));

python

import json
import os

import requests

response = requests.post(
    "https://api.x.ai/v1/videos/edits",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok-imagine-video",
        "prompt": "Give the woman a silver necklace",
        "video": {
            "url": os.environ["VIDEO_URL"],
        },
    },
)

print(json.dumps(response.json(), indent=2))

响应示例:

json

{
  "request_id": "a3d1008e-4544-40d4-d075-11527e794e4a"
}

POST /v1/videos/extensions

通过生成延续内容扩展视频。这是一个异步操作，返回一个用于轮询的 request_id。

请求体

duration (integer | null) — 要生成的扩展片段的时长（秒）（2-10）。如果未指定，默认为 6 秒。
model (string | null) — 要使用的模型。
output (object)
- upload_url (string, required) — 用于通过 HTTP PUT 上传生成视频的签名 URL。
prompt (string, required) — 描述视频中接下来应发生什么的提示词。
storage_options (object)
- expires_after (integer | null) — 从现在起文件自动过期前的秒数。最大 2592000（30 天）。如果省略，文件永不过期。
- filename (string, required) — 存储文件的文件名。
- public_url (boolean | object)
video (object, required) — 编辑和扩展请求的视频输入。接受公共 URL、base64 编码的数据 URL 或来自 xAI Files API 的 file_id。
- file_id (string | null) — 来自 xAI Files API 的文件 ID。与 url 互斥。文件必须是视频（例如 MP4）且已完全上传。
- url (string) — 视频的 URL（公共 URL 或 base64 编码的数据 URL）。视频必须具有 .mp4 文件扩展名，并使用 .mp4 支持的编解码器（如 H.265、H.264、AV1 等）进行编码。当未设置 file_id 时必需。

响应体

request_id (string, required) — 用于轮询结果的唯一请求 ID。

请求示例:

json

{
  "prompt": "The camera slowly zooms out to reveal the city skyline",
  "video": {
    "url": "https://example.com/video.mp4"
  },
  "model": "grok-imagine-video",
  "duration": 6
}

响应示例:

json

{
  "request_id": "a3d1008e-4544-40d4-d075-11527e794e4a"
}

GET /v1/videos/

获取延迟的视频生成请求结果。

路径参数

request_id (string, required) — 之前的视频生成请求返回的延迟请求 ID。

响应体

error (object)
- code ("invalid_argument" | "permission_denied" | "failed_precondition" | "service_unavailable" | "internal_error", required) — 视频生成故障的机器可读错误代码。
  这些是轮询延迟视频生成结果时可能出现在 VideoError.code 中的代码。身份验证、模型未找到和同步速率限制错误作为 HTTP 错误返回，永远不会出现在 VideoError 中。生成过程中遇到的引擎过载在此处显示为 service_unavailable（HTTP 503）。
  为兼容 JSON，序列化为/from 驼峰字符串（例如 "invalid_argument"、"internal_error"）。
- message (string, required) — 描述故障的可读错误消息。
model (string | null) — 用于生成视频的模型。状态为 "failed" 时省略。
progress (integer | null) — 视频生成任务的近似完成百分比（0-100）。
- 当状态为 "pending"：进度在 0-99 之间，表示当前完成度。
- 当状态为 "done"：进度为 100。
- 当状态为 "failed"：省略进度。
status (string, required) — 视频生成状态：视频准备好时为 "done"。
usage (object)
- cost_in_usd_ticks (integer, required) — 此请求的成本，以 USD ticks 表示。一美分等于 100,000,000 ticks，因此一美元等于 10,000,000,000 ticks。
video (object)
- duration (integer, required) — 生成视频的时长（秒）。
- file_output (object)
  - expires_at (integer | null) — 存储文件过期并将被自动删除的 Unix 时间戳（秒）。仅在文件有过期时间时存在。
  - file_id (string, required) — 存储文件的 Files API file_id。
  - filename (string, required) — 存储文件的文件名。
  - public_url (string | null) — 存储文件的公共 URL。仅在请求包含 storage_options.public_url 且创建成功时存在。
  - public_url_error (string | null) — 当 storage_options.public_url 设置但公共 URL 创建失败时的可读错误。文件已成功存储。
  - public_url_expires_at (integer | null) — 公共 URL 过期的 Unix 时间戳（秒）。当公共 URL 有过期时间时存在，无论是来自请求中的显式 expires_after 还是继承自文件的 TTL。
- respect_moderation (boolean, required) — 模型生成的视频是否遵守审核规则。如果视频遵守审核规则，该字段将为 true。否则该字段将为 false 且视频 url 字段将为空。
- storage_error (string | null) — 当 storage_options 设置但上传失败时的可读错误。成功或未请求存储时不存在。
- url (string | null) — 生成视频的 URL。

代码示例

bash

curl -s "https://api.x.ai/v1/videos/$VIDEO_REQUEST_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"

javascript

const response = await fetch(
  `https://api.x.ai/v1/videos/${process.env.VIDEO_REQUEST_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    },
  },
);

console.log(JSON.stringify(await response.json(), null, 2));

python

import json
import os

import requests

request_id = os.environ["VIDEO_REQUEST_ID"]

response = requests.get(
    f"https://api.x.ai/v1/videos/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))

响应示例:

json

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/xai-vidgen-bucket/xai-video-{request_id}.mp4",
    "duration": 6,
    "respect_moderation": true
  },
  "model": "grok-imagine-video"
}

推理 API ​

视频 ​

POST /v1/videos/generations ​

请求体 ​

响应体 ​

代码示例 ​

POST /v1/videos/edits ​

请求体 ​

响应体 ​

代码示例 ​

POST /v1/videos/extensions ​

请求体 ​

响应体 ​

GET /v1/videos/ ​

路径参数 ​

响应体 ​

代码示例 ​

推理 API

视频

POST /v1/videos/generations

请求体

响应体

代码示例

POST /v1/videos/edits

请求体

响应体

代码示例

POST /v1/videos/extensions

请求体

响应体

GET /v1/videos/

路径参数

响应体

代码示例