# Videos（仅 Grok） Grok/xAI 文生视频与视频编辑。**Videos 只支持 Grok 分组**,不是 OpenAI/Codex 能力。视频生成通常较慢,多为**异步任务**:先提交,再轮询结果。 ```text POST https://api.clomio.ai/v1/videos POST https://api.clomio.ai/v1/videos/generations POST https://api.clomio.ai/v1/videos/edits POST https://api.clomio.ai/v1/videos/extensions GET https://api.clomio.ai/v1/videos GET https://api.clomio.ai/v1/videos/{request_id} ``` > **分组要求:** **仅 Grok 分组**支持视频,且该分组必须启用视频能力;其他分组返回 404 `Videos API is not supported for this platform`,Grok 分组未开启视频能力时返回 403 `Video generation is not enabled for this group`。见 [端点 × 分组](#/api-usage)。 > > **接口形态:** 视频生成通常是异步任务。推荐使用 `POST /v1/videos/generations`、`POST /v1/videos/edits`、`POST /v1/videos/extensions`，再用 `GET /v1/videos/{request_id}` 查询；根路径仅作为兼容入口，不建议新客户端使用。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥` | | `Content-Type` | POST 时是 | `application/json`(编辑/带图时用 `multipart/form-data`)；GET 轮询通常不需要请求体 | --- ## 网关处理边界 - 路由层仅 Grok 分组可进入；OpenAI/Claude/其他分组返回 404 `Videos API is not supported for this platform`。 - 服务支持 `model`、`prompt`、`duration`、`aspect_ratio`、`resolution` 以及兼容字段 `seconds`、`size`。`image`、`reference_images`、`input_reference`、`user` 等字段会按原请求发送；字段必填和取值范围以所选 Grok 视频模型说明为准。 - 成功的创建、编辑和延展请求会按时长、分辨率和变体数量计费；GET 查询只返回任务状态或内容，不重复计费。下载子路径如果返回二进制内容，客户端应按响应 `Content-Type` 保存。 --- ## 文生视频:generations ### 请求参数 | 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `model` | string | 通常必填 | 视频模型名,以当前 Grok 分组可用模型为准 | | `prompt` | string | 通常必填 | 画面描述;具体必填和长度限制以视频模型为准 | | `duration` | number | 否 | xAI 官方时长字段,通常 1-15 秒;老客户端也可能传 `seconds` | | `aspect_ratio` | string | 否 | xAI 官方画幅字段,如 `16:9`、`9:16`、`1:1`;老客户端也可能传 `size` | | `resolution` | string | 否 | xAI 官方分辨率字段,如 `480p`、`720p`、`1080p`;老客户端也可能传 `size`/`1280x720` | | `n_variants` | number | 否 | 生成变体数量;用于计费/统计时会计入视频数量 | | `image` / `reference_images` / `input_reference` | object/array | 否 | 图生视频或参考图视频输入,具体以 Grok/xAI 模型为准 | | `user` | string | 否 | 透传给上游的最终用户标识 | Grok 视频响应通常使用 `request_id`、`status`、`video` 或 `data` 等字段。服务保留这些字段，客户端应按实际响应读取；同时兼容旧客户端的 `seconds`、`size`、`n_variants`/`n` 写法。 ### 响应 提交后通常返回一个**异步任务对象**。xAI 官方常见返回 `request_id`;轮询状态以 `pending` / `done` / `expired` / `failed` 为准: ```json { "request_id": "video_xxx", "object": "video", "status": "pending", "model": "你的 Grok 视频模型名" } ``` --- ## 查询结果:GET /v1/videos 或 GET /v1/videos/{request_id} 这是 Grok 视频任务查询入口；返回任务列表、详情或其它结构以所选模型的响应格式为准。 ```bash curl https://api.clomio.ai/v1/videos/video_xxx \ -H "Authorization: Bearer 你的 Grok 分组密钥" ``` 完成后返回里可能带视频地址、下载子路径或可直接下载内容,字段以所选模型为准。不要假设 `data[0].url` 永远存在；xAI 官方示例常见完成响应是 `status:"done"` 且视频地址在 `video.url`。先打印响应,再按 `video.url`、`data[].url`、顶层 `url`、`download_url`、`content` 下载子路径或上游文档说明处理。上游返回的视频 URL 可能是临时 URL,生产环境建议成功后立刻下载/转存。 ```json { "request_id": "video_xxx", "status": "done", "video": { "url": "https://.../output.mp4" }, "data": [{ "url": "https://.../output.mp4" }], "url": "https://.../output.mp4" } ``` --- ## 最小可验证 curl “提交生成 + 轮询”示例可验证 Grok-only 路由、视频能力开关、POST 透传和 GET `/v1/videos/{request_id}` 轮询透传；用 OpenAI/Claude 分组 Key 调同一路径可验证 404 `Videos API is not supported for this platform`。 ## 示例:提交生成 + 轮询 ```bash # 1) 提交 curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "你的 Grok 视频模型名", "prompt": "海边日落,海鸥飞过,电影质感", "duration": 8, "aspect_ratio": "16:9", "resolution": "720p" }' # 2) 用返回的 request_id 轮询,直到 status 为 done curl https://api.clomio.ai/v1/videos/video_xxx \ -H "Authorization: Bearer 你的 Grok 分组密钥" ``` ```python import time, requests create_url = "https://api.clomio.ai/v1/videos/generations" headers = {"Authorization": "Bearer 你的 Grok 分组密钥"} job = requests.post(create_url, headers=headers, json={ "model": "你的 Grok 视频模型名", "prompt": "海边日落,海鸥飞过,电影质感", "duration": 8, "aspect_ratio": "16:9", "resolution": "720p", }).json() vid = job.get("request_id") while True: r = requests.get(f"https://api.clomio.ai/v1/videos/{vid}", headers=headers).json() if r.get("status") in ("done", "failed", "expired"): print(r) break time.sleep(5) ``` ### 完整场景:生成 → 轮询 → 下载到本地 ```python import time, requests CREATE_URL = "https://api.clomio.ai/v1/videos/generations" H = {"Authorization": "Bearer 你的 Grok 分组密钥"} job = requests.post(CREATE_URL, headers={**H, "Content-Type": "application/json"}, json={ "model": "你的 Grok 视频模型名", "prompt": "雨后的城市街道,霓虹倒影,赛博朋克风格", "duration": 6, "aspect_ratio": "16:9", "resolution": "720p", }).json() vid = job.get("request_id") print("任务已提交:", vid) # 轮询直到完成 while True: r = requests.get(f"https://api.clomio.ai/v1/videos/{vid}", headers=H).json() st = r.get("status") print("状态:", st) if st == "done": url = ( (r.get("video") or {}).get("url") or (r.get("data") or [{}])[0].get("url") or r.get("url") or r.get("download_url") ) if not url: print("已完成,但响应未提供直接 URL;请按上游字段或 content 子路径下载:", r) break open("output.mp4", "wb").write(requests.get(url).content) print("已下载 output.mp4") break if st in ("failed", "expired"): print("生成失败:", r); break time.sleep(8) # 视频较慢,间隔大一些,避免触发限速 ``` --- ## 视频编辑 / 延展 - `POST /v1/videos/edits` —— 基于输入视频编辑;官方形态通常是 JSON 里提供 `video:{url|file_id|data URL}` 与 `prompt` - `POST /v1/videos/extensions` —— 延长已有视频;官方形态通常也是 JSON 引用已有视频 字段与具体能力随模型而定,以控制台「视频模型」说明和 Grok/xAI 接口为准。编辑/延展请求可以使用模型要求的 JSON 或 multipart 格式；如果接口要求 JSON `video` 字段,不要误以为必须 multipart 上传。 ### 高级视频场景边界 - **image-to-video**:请求通常包含 `prompt` + `image`。如果不显式传 `aspect_ratio`,模型可能按输入图片比例生成;显式传入时可能出现拉伸或裁切,以模型为准。 - **reference-to-video**:请求通常包含 `prompt` + `reference_images`。公开 xAI 形态常限制参考图数量和最长时长;新接入按当前上游文档与控制台说明填写。 - **editing / extension**:编辑和延展不是普通文生视频参数的超集;有些模型不接受自定义 `duration`、`aspect_ratio`、`resolution`。不要把 generations 的字段原样复制到 edits/extensions。 ## 排障 | 现象 | 常见原因 | 处理 | |------|----------|------| | 404 `Videos API is not supported for this platform` | API Key 不在 Grok 分组 | 换 Grok 分组 Key | | 403 `Video generation is not enabled for this group` | 当前 Grok 分组未开放视频能力 | 更换已开放 Grok Videos 的分组；如应已开放，带 `x-request-id` 提交工单 | | 503 `No available compatible accounts for video generation` | 暂时没有可用的视频生成服务能力、上游限流或模型能力不匹配 | 降低并发稍后重试；确认模型和分组支持视频；持续失败带 `x-request-id` 提交工单 | | 503 `No available accounts after failover` | 自动切换后仍没有可用服务能力 | 稍后重试或换分组；持续失败带 `x-request-id` 和错误体提交工单 | | 429 Too Many Requests | 轮询太频繁、创建端触发 xAI per-model RPS/TPM 或服务侧限速 | 轮询间隔 5~10 秒以上；创建端按 `Retry-After` / rate-limit headers/backoff 处理；持续异常带 `x-request-id` 提交工单 | | 502/上游错误 `get access token for video: ...` / `missing token for video generation` | Grok 视频服务或凭证暂时异常 | 稍后重试；持续出现时带 `x-request-id`、时间和错误体提交工单 | | 上游 4xx/5xx 原样返回 | 字段缺失、模型不支持或服务繁忙 | 查看错误 body，并按视频模型要求调整请求 | --- > 视频能力目前仅 Grok 分组开放;图像见 [Images](#/api-images)。轮询间隔建议 5~10 秒,避免触发[限速](#/troubleshooting)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前 Grok 分组中的 `grok-imagine-video*` | 必填 | | `prompt` | 非空 string | 文生视频描述 | | `duration` | 通常 `1..15` 秒 | `seconds` 是旧兼容字段 | | `aspect_ratio` | `1:1`、`16:9`、`9:16` 等 | 以模型支持列表为准 | | `resolution` | `480p`、`720p`、`1080p`、`4k` | 以模型支持列表为准 | | `n_variants` / `n` | 正整数 | 变体数量，受上游限制 | | `image` | object，通常包含 `url` | 图生视频输入 | | `reference_images` | array，通常最多 7 项 | 参考图视频；同时使用 image 时可能冲突 | ## 状态与错误响应 ```json {"request_id":"video_xxx","status":"pending","model":"grok-imagine-video"} ``` 轮询终态通常是 `done`、`failed` 或 `expired`；完成响应可能在 `video.url`、顶层 `url` 或 `data[].url` 提供下载地址。 | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `model/prompt is required`、duration/resolution 不合法 | 按模型参数范围修正 | | 403 | `Video generation is not enabled for this group` | 开启 Grok 视频能力或换分组 | | 404 | `Videos API is not supported for this platform` | 使用 Grok 分组 Key | | 409/422 | 任务状态或输入视频不符合要求 | 检查 request_id、video 引用和终态 | | 429 | 创建/轮询过频 | 创建按 Retry-After 退避，轮询间隔 5~10 秒 | | 502/503 | 视频服务暂时不可用 | 保存 `x-request-id` 和原始错误体 |