9router-video

9Router — 视频生成（xAI Grok Imagine）

需要配置 NINEROUTER_URL（若启用了鉴权，还需配置 NINEROUTER_KEY）。设置方法参见 https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md。

需要在 9Router 控制台中连接一个 xAI 账户，可以是 Grok Build OAuth（使用 SuperGrok / X Premium+ 订阅登录），也可以是来自 console.x.ai 的 xAI API 密钥。两者是不同的鉴权类型，计费方式也不同，控制台会显示每个连接使用的是哪一种。

端点（异步任务流程）

视频生成是异步的：POST 请求会立即返回 request_id，之后需要轮询，直到任务状态为 done 或 failed。

端点	用途
POST /v1/videos/generations	文生视频 / 图生视频
POST /v1/videos/edits	编辑已有视频
POST /v1/videos/extensions	扩展已有视频
GET /v1/videos/{request_id}	轮询任务状态

请求字段（原样透传给 xAI，参见 https://docs.x.ai/developers/rest-api-reference/inference/videos）：

字段	是否必填	说明
model	否	xai/grok-imagine-video（发送到上游前会去掉 xai/ 前缀）
prompt	文生视频时必填	视频描述
duration	否	时长，单位为秒
aspect_ratio	否	16:9、9:16、1:1、4:3、3:4、3:2、2:3
resolution	否	480p、720p、1080p
image	否	图生视频时使用，格式为 { "url": "https://… 或 data:image/…;base64,…" }
video	编辑 / 扩展时必填	{ "url": "…mp4" } 或 { "file_id": "…" }

示例

提交任务：

curl -X POST "$NINEROUTER_URL/v1/videos/generations" \
  -H "Authorization: Bearer $NINEROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"xai/grok-imagine-video","prompt":"A cinematic tracking shot through a neon city at night","duration":8,"aspect_ratio":"16:9","resolution":"720p"}'
# → {"request_id":"abc123"}   (response header x-9router-connection-id: <id>)

轮询直到完成（回传连接请求头，确保由同一账户轮询该任务）：

curl "$NINEROUTER_URL/v1/videos/abc123" \
  -H "Authorization: Bearer $NINEROUTER_KEY" \
  -H "x-connection-id: <id from create response>"
# → {"status":"pending","progress":42}
# → {"status":"done","video":{"url":"https://…mp4","duration":8},"model":"grok-imagine-video"}
# → {"status":"failed","error":{"code":"…","message":"…"}}

下载：从 done 状态的响应中获取 video.url 并下载。

命令行一次性执行

9router xai video \
  --prompt "A cinematic tracking shot through a neon city at night" \
  --output video.mp4
# options: --model --duration --aspect-ratio --resolution --image --timeout --port --api-key

该命令会提交任务、带进度显示地轮询，并将视频下载到 video.mp4.part，成功后原子性地重命名。按 Ctrl+C 可干净地取消；失败时以非零退出码结束。

注意事项与限制

• 上游任务与账户绑定：轮询时必须使用创建该任务的同一连接（使用 x-connection-id 请求头，其值来自创建响应中的 x-9router-connection-id）。
• 创建任务的 POST 请求永远不会自动重试（重试可能会创建并计费两个视频）。仅会执行一次 401→刷新令牌→单次重试，此类请求在上游创建任务之前即被拒绝。
• 视频模型带有 kind: "video" 标记，会被排除在聊天模型列表和聊天回退组合之外。
• Grok Build 订阅 OAuth 令牌与 API 密钥会发送到相同的 api.x.ai/v1/videos 端点；某一订阅等级是否包含视频生成配额由 xAI 决定，9Router 不做验证。上游返回 403/permission_denied 即表示所连接的账户没有视频功能权限。