OpenAI 兼容层

查询视频任务

用提交时拿到的 task_id 查询任务进度，status 变成 succeeded 或 failed 就停止轮询。

GET/v1/videos/{task_id}

端点

GET /v1/videos/{task_id}                # 查询状态

同一能力在原生透传层的写法见 查询视频任务（原生透传）。

这里的 ID 是 task_id，不是 request_id

兼容层用 task_id，原生透传层用 request_id，两者不通用。拿 request_id 来这里查会找不到任务。

请求

curl "https://api.wxiai.com/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $WXIAI_API_KEY"

状态值

status	含义	是不是终态
queued	排队中	否
processing	生成中	否
succeeded	完成	是
failed	失败	是

看到 succeeded / failed 就退出轮询。超时（600 秒）后按 failed 处理。

成功和失败都返回 HTTP 200

失败时也是 HTTP 200，错误放在 status 和 error 里。别写「HTTP 200 就当成功」——一定读 status。

返回

生成中：

{
  "task_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf",
  "status": "processing"
}

完成：

{
  "task_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf",
  "status": "succeeded",
  "url": "https://vidgen.x.ai/.../video.mp4",
  "format": "mp4",
  "metadata": {
    "duration": 8,
    "width": 1280,
    "height": 720
  }
}

字段	说明
task_id	任务 ID，和提交时返回的一致
status	见上方状态表
url	视频地址，succeeded 时才有。通常是上游直链；回退时会是本网关的 /v1/videos/{task_id}/content 代理地址（该端点非 xAI 官方，见下）
format	容器格式，一般是 mp4
metadata	duration（秒）、width、height；取不到就不返回
error	failed 时的错误对象，含 code（数字）和 message

失败：

{
  "task_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf",
  "status": "failed",
  "error": { "code": 500, "message": "生成失败：……" }
}

提交/轮询被上游同步拒绝时的形态（HTTP 4xx）

创建任务之前就失败的请求，走的是标准 API 错误信封（和所有兼容层接口一致）：

{
  "error": {
    "message": "Generated image rejected by content moderation.",
    "type": "wxi_api_error",
    "param": "prompt",
    "code": "invalid_request_error"
  }
}

这不是任务状态，error 是一个对象且一定有 message。区别见 错误码。

下载视频文件（本网关额外提供）

curl "https://api.wxiai.com/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  --output video.mp4

直接返回文件流，适合后端落盘或转发给前端。

这个端点不是 xAI 官方的

xAI 官方只有 GET /v1/videos/{request_id}，没有 /content。 它返回的 video.url 就是可直接下载的地址。

/v1/videos/{task_id}/content 是本网关为了方便而额外提供的下载代理——当 url 回退成网关地址时，用它把文件流拿回来。想少一跳就直接下 url。

这一层的注意点

• 别把轮询写成死循环：服务端 600 秒后判定超时并退还本次额度；客户端也要有自己的超时上限。
• 轮询间隔别太短：服务端 10 秒查一次上游，客户端 5 秒左右足够，更密也不会更快。
• metadata 可能整体缺失：别强依赖 width / height，拿不到就自行探测。
• url 是临时地址：succeeded 后尽快下载。要长期保存就用提交时的 storage_options。

相关页

• 视频生成总览 —— 轮询节奏、超时与退款规则
• 查询视频任务（原生透传） —— 同一能力的另一条路径
• 生成视频（OpenAI 兼容） · 编辑视频（OpenAI 兼容） · 扩展视频（OpenAI 兼容）
• 错误码