Grok 视频格式（Video）

本文档旨在说明如何通过 New-API 调用 xAI 的 Grok 系列模型。目前支持视频生成，计费逻辑全面支持动态参数。

1. 通用请求信息

• 基准地址 (Base URL): https://api-cs-al.naci-tech.com/v1
• 认证方式: 携带 Authorization: Bearer $API_KEY 请求头
• 内容类型: Content-Type: application/json

关于 metadata 透传

New-API 会对请求体中的 metadata 对象进行**全透明透传**。凡是 xAI 原生支持、但未在标准字段表中列出的高级参数（如 seed、negative_prompt、aspect_ratio、fps 等），都可以直接放在 metadata 中传递。

---

2. 视频生成模型（grok-imagine-video）

支持文本生成视频、图像生视频、视频生视频（Remix）等功能。

透明透传（重点）

New-API 会对 metadata 对象进行**全透明透传**。很多 xAI 原生参数（例如 aspect_ratio、seed、fps），以及本文档中部分“模式开关”字段（例如 resolution、video）都建议放在 metadata 里。

API 端点

• 创建视频任务：POST /v1/video/generations

基本请求参数

参数名	类型	必填	说明
model	string	是	固定为 grok-imagine-video
prompt	string	是	视频内容的文字描述
duration	integer	否	视频时长（秒），仅文本/图生视频有效，范围 1–15，默认 5。视频编辑（Remix）模式下不可用，输出时长与输入视频一致且上限 8.7 秒
metadata	object	否	附加元数据（透传对象），支持下表中的字段
images	array	否	输入图片数组，用于 Image-to-Video 模式
image	string	否	输入单张图片：可为图片 公网 URL，或 base64 数据 URI（如 data:image/jpeg;base64,...），与 images 二选一即可

Metadata 字段

字段名	类型	说明
resolution	string	输出分辨率：720p（高清）、480p（标清，默认，处理更快）。仅文本/图生视频有效；视频编辑模式下不支持，输出与输入视频分辨率一致且上限 720p
aspect_ratio	string	画面比例，仅文本/图生视频有效。可选：1:1、16:9（默认）、9:16、4:3、3:4、3:2、2:3。图生视频不传时默认与输入图一致；视频编辑模式下不支持，输出与输入视频一致
video	string	输入视频 URL。提供此字段将触发 Video-to-Video（Remix）模式

示例请求 1：文本 + 图片生成视频

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "一座在云端的赛博朋克城市",
    "duration": 5,
    "image": "https://example.com/init_frame.png",
    "metadata": {
      "resolution": "720p"
    }
  }'

示例请求 2：视频生视频（Video-to-Video / Remix）

要在已有视频基础上进行重绘 or 修改，需在 metadata 中传入 video 参数。

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "将视频风格转为梵高油画风格",
    "metadata": {
      "video": "https://example.com/original_video.mp4"
    }
  }'

---

3. 视频任务状态查询

提交成功后会返回 id（即 task_id），可使用以下接口查询生成进度及结果：

• GET /v1/videos/<id>
• GET /v1/video/generations/<id>

查询示例（curl）

示例 1：通过 GET /v1/videos/<id> 查询（OpenAI 风格）

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

示例 2：通过 GET /v1/video/generations/<id> 查询（agtcloud 风格）

curl -X GET "https://api-cs-al.naci-tech.com/v1/video/generations/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

返回值说明（标准 OpenAI 视频格式）

• status: queued（排队中）、in_progress（生成中）、completed（成功）、failed（失败）
• progress: 任务完成进度（0-100）
• metadata.url: 生成完成后的视频直链地址
• error: 任务失败时的错误信息对象

典型返回示例

{
  "id": "xai-task-12345",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1718300000,
  "metadata": {
    "url": "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content"
  }
}

---

4. 获取视频文件内容（Proxy）

如果你需要直接获取视频文件流（例如用于前端 <video> 标签播放），可使用以下代理接口：

请求路径: GET /v1/videos/<id>/content

请求示例（curl）

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content" \
  -H "Authorization: Bearer $API_KEY" \
  --output "output_video.mp4"

说明

• 该接口会直接透传上游视频文件的二进制流
• 包含正确的 Content-Type（如 video/mp4）及缓存控制头
• 权限：同样需要携带有效的 Authorization 令牌

---

5. 计费逻辑说明（透明化计费）

New-API 会根据你上传的参数动态计算额度消耗（包括部分在 metadata 中透传的参数），因此建议在业务侧将 metadata 一并记录，便于对账与复现。