Grok CLI Manual

视频生成

Grok Build 与 REST 共用 xai_api_base_url；手动调用 REST 时，创建成功后应立即保存 Router 返回的 request_id。

配置视频端点

视频工具与图片工具共用 xai_api_base_url：

[endpoints]
models_base_url = "https://api.xairouter.com"
xai_api_base_url = "https://api.xairouter.com"

[auth]
preferred_method = "api_key"

两项都填写不带 /v1 的 XAI Router 主 API 域名。Grok Build 会在 xai_api_base_url 后追加 /videos/...；直接调用 REST API 时则使用标准的 /v1/videos/... 路径。模型、图片和视频请求使用同一个 XAI Router 用户 Key。

在 Grok Build 中生成视频

当前版本可以直接使用：

/imagine-video 一艘晶体动力飞船从火星峡谷升空，电影感广角镜头，16:9

/imagine-video 会先用 image_gen 生成首帧，再调用 image_to_video；它不是纯文本直出视频工具。生成完成后，文件保存在当前会话的 videos/<编号>.mp4，回复中会给出可点击路径。

已有一张图片时，可以明确要求动画化：

请调用 image_to_video，将 /absolute/path/to/first-frame.jpg 动画化：镜头缓慢推进，风吹动背景中的树叶，时长 6 秒，720p。

需要多张内容或风格参考时，使用 reference_to_video：

请调用 reference_to_video，使用 /absolute/path/to/subject.jpg 和 /absolute/path/to/style.jpg 生成 16:9、6 秒、720p 的电影感镜头。

当前 Grok Build 工具的约束与直接调用 API 不完全相同：

image_to_video 使用 1.5 质量模型，reference_to_video 使用基础视频模型；模型由工具和 Router 自动选择，不能通过工具参数修改。Grok Build 会代管 request_id、每 5 秒轮询一次，并在最多 5 分钟后停止等待；本页后文的 ID 保管要求针对手动 REST 调用。

本地图片会被转成 base64 放入请求体。多图时优先使用可信的 HTTPS URL，以减少上传体积和内存占用。

直接调用 Videos API

直接调用时推荐使用稳定模型名 grok-imagine-video-1.5。先确认 Router 已向当前账号发布并允许该模型：

curl -fsS https://api.xairouter.com/v1/models \
  -H 'Authorization: Bearer YOUR_XAI_ROUTER_KEY' \
  | jq -r '.data[].id' | grep '^grok-imagine-video'

模型列表反映 Router 的目录与访问规则，不会实时探测所选上游账号的 Imagine 权限；实际权限和额度仍以调用结果为准。

REST API 接受 1–15 秒的整数时长。常用比例包括 1:1、16:9、9:16、4:3、3:4、3:2 和 2:3。参考图生成最高为 720p；当前 Router 视频链路开放创建与状态轮询，不包含官方的编辑和延长端点。

下面是一份完整的文本转视频脚本。它会立即保存创建响应和 request_id，轮询到完成，再下载临时视频 URL：

set -euo pipefail

BASE_URL="https://api.xairouter.com"
ROUTER_API_KEY="YOUR_XAI_ROUTER_KEY"
JOB_FILE="grok-video-job.json"
STATUS_FILE="grok-video-status.json"

curl -fsS "$BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A crystal-powered spacecraft rises from a Martian canyon, cinematic wide shot",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' > "$JOB_FILE"

REQUEST_ID="$(jq -er '.request_id | strings | select(startswith("vjob_"))' "$JOB_FILE")"
printf 'request_id=%s\n' "$REQUEST_ID"

MAX_POLLS=120
VIDEO_URL=""

for ((ATTEMPT = 1; ATTEMPT <= MAX_POLLS; ATTEMPT++)); do
  if ! curl -fsS --retry 3 --retry-delay 2 --retry-max-time 20 --retry-connrefused \
    "$BASE_URL/v1/videos/$REQUEST_ID" \
    -H "Authorization: Bearer $ROUTER_API_KEY" > "$STATUS_FILE"; then
    printf 'poll failed; request_id remains saved in %s\n' "$JOB_FILE" >&2
    exit 1
  fi
  STATUS="$(jq -r '.status // empty' "$STATUS_FILE")"

  case "$STATUS" in
    done)
      VIDEO_URL="$(jq -er '.video.url' "$STATUS_FILE")"
      break
      ;;
    failed|expired)
      jq . "$STATUS_FILE" >&2
      exit 1
      ;;
    pending)
      sleep 5
      ;;
    *)
      jq . "$STATUS_FILE" >&2
      exit 1
      ;;
  esac
done

if [[ -z "$VIDEO_URL" ]]; then
  printf 'poll timed out; request_id remains saved in %s\n' "$JOB_FILE" >&2
  exit 1
fi

curl -fL --retry 3 --retry-delay 2 "$VIDEO_URL" --output grok-video.mp4

单图转视频只需在创建请求中增加：

"image": {"url": "https://example.com/first-frame.jpg"}

多参考图模式则使用：

"reference_images": [
  {"url": "https://example.com/subject.jpg"},
  {"url": "https://example.com/style.jpg"}
]

image 与 reference_images 代表不同模式，不要在同一次请求中混用。

正确保管 request_id

创建成功后，XAI Router 返回以 vjob_ 开头的公开任务 ID。它会把后续轮询固定到创建任务时的同一上游账号；客户端必须将它视为不透明字符串，并使用同一 Router 用户的 Key 原样请求 GET /v1/videos/{request_id}。

当前没有视频任务列表、历史查询或按其他条件找回任务的接口。忘记或丢失 request_id 后无法恢复轮询，因此应像上面的脚本一样先保存完整创建响应。任务完成后的 video.url 也是临时地址，需要保留成品时应尽快下载。

创建请求是非幂等操作。如果 POST 超时或连接中断，不要盲目自动重提，因为上游可能已经创建任务并产生费用。示例最多轮询约 10 分钟，并只对安全的状态 GET 做有限重试；202 和 pending 都表示仍在生成。

计费规则

携带用户 Key 查询当前账号的最终视频单价：

curl -fsS https://api.xairouter.com/x-pricing \
  -H 'Authorization: Bearer YOUR_XAI_ROUTER_KEY' \
  | jq '.data[] | select(.category == "VideoPricing") | {id, unit, final}'

创建请求返回 2xx 后，Router 按提交的时长、分辨率和输入图片数立即计费；轮询不重复计费。未填写时长或分辨率时，计费默认值分别为 6 秒和 480p。任务后来变为 failed 或 expired 时不会自动退款或补差，因此应在提交前核对参数和当前 /x-pricing。

/imagine-video 默认会先调用一次 image_gen 生成首帧，再提交一次视频创建，所以总费用包含图片生成费和视频费；直接用已有图片调用 image_to_video 时没有这笔首帧生成费。多镜头工作流会对每个镜头分别计费。

排查要点

• /imagine-video 不可用：更新 Grok Build，并确认视频工具没有被环境变量、远程策略或工具 denylist 禁用。
• 请求直达 xAI 后 Key 报错：检查 xai_api_base_url，并确保 XAI_API_KEY、GROK_CODE_XAI_API_KEY 没有覆盖 Router Key。
• 400 或模型不可用：直接 API 优先使用稳定模型名，并先确认它已在 GET /v1/models 中发布；该列表不保证上游实时权限。
• 403 或 429：检查当前上游账号的 Imagine 权限、额度和频率限制。
• 轮询返回 503 任务账号不可用：创建任务所用的精确上游 Key 可能已删除或禁用；Router 不会切换到其他账号。
• 轮询返回 400 invalid video request_id：任务创建后，上游 Key 可能换密或修改了 Provider/Config，原签名因此失效。
• 账户启用了 Resources 白名单：标准 API 至少开放 /v1/videos，Grok Build 还需开放 /videos。
• 请求体过大：本地和 base64 图片会膨胀；Router 默认请求体上限为 200 MiB，优先改用 HTTPS URL。

模型能力与参数以 xAI 视频生成指南、Grok Imagine Video 1.5 模型页和 Image-to-Video 指南为准。