Grok 视频生成 API 开发手册

本文档适用于 FriModel 对外接口：

https://api.pinniq.org

官方 xAI 视频接口参考：

https://docs.x.ai/developers/rest-api-reference/inference/videos#video-generation

不要把 API Key 写进代码仓库。下面 curl 示例统一使用环境变量：

本文档基于原始 Grok 视频调用文档整理，并补充 FriModel 平台实测结论：旧文档里的最终视频地址字段主要写作 metadata.url，当前 Grok 任务完成响应实测主要返回顶层 video_url。客户端应优先读取 video_url，并兼容 metadata.url。

1. 接入结论

Grok 视频生成是异步任务接口：

调用 POST /v1/videos 创建任务。

从创建响应里取 task_id。

调用 GET /v1/videos/{task_id} 轮询任务状态。

当 status=completed 且 progress=100 时下载视频。

完成后有两种取视频方式：

方式	说明	是否需要鉴权
查询响应里的 `video_url`	上游返回的 mp4 直链，当前 Grok 任务实测返回这个字段	通常不需要额外鉴权
`/v1/videos/{task_id}/content`	FriModel 平台代理下载地址，由 `task_id` 拼接得到	需要 `Authorization: Bearer ...`

推荐客户端优先支持 /content 下载，因为它只依赖平台任务 ID：

注意：pinniq.org 是控制台域名，不作为 API 调用入口。API 请求请使用 api.pinniq.org。

2. 支持模型

模型	纯文字生成视频	图片生成视频	说明
`grok-imagine-video`	支持	支持	适合纯文本或图生视频
`grok-imagine-video-1.5-preview`	不支持	支持	必须传图片

使用建议：

纯文字视频：使用 grok-imagine-video。

图片生成视频：两个模型都可以用，优先按业务效果选择。

grok-imagine-video-1.5-preview 如果只传 prompt，可能返回 Text-to-video is not supported for this model.。

3. 创建任务

3.1 纯文字生成视频

仅适用于 grok-imagine-video。

创建成功示例：

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1710000000,
  "seconds": "4",
  "size": "720x1280"
}

说明：请求 duration=5 时，实际返回的 seconds 可能由上游调整，例如实测返回 "4"。客户端应以接口返回的 seconds 为准。

3.2 图片生成视频

推荐使用 multipart/form-data 上传图片，字段名使用 input_reference。

grok-imagine-video 也可以用图片生成视频：

multipart 表单建议传 seconds。JSON 请求建议传 duration。

4. 创建任务参数

字段	类型	必填	说明
`model`	string	是	`grok-imagine-video` 或 `grok-imagine-video-1.5-preview`
`prompt`	string	是	视频提示词
`duration`	int/string	否	JSON 请求中的视频秒数
`seconds`	int/string	否	multipart 表单中的视频秒数
`input_reference`	file/string	图生视频必填	multipart 文件、图片 URL 或 data URL
`image`	string	否	图片 URL 或 data URL，作为兼容字段
`images`	string[]	否	多图兼容字段，当前通常只取第一张

图片格式建议：JPEG、PNG、WebP。

5. 查询任务

生成中示例：

{
  "id": "task_xxx",
  "model": "grok-imagine-video",
  "object": "video",
  "progress": 68,
  "status": "queued"
}

完成示例：

{
  "id": "task_xxx",
  "model": "grok-imagine-video",
  "object": "video",
  "progress": 100,
  "seconds": "4",
  "status": "completed",
  "video_url": "https://vidgen.x.ai/xai-vidgen-bucket/xai-video-xxx.mp4"
}

字段说明：

字段	说明
`id`	平台任务 ID
`task_id`	兼容字段。创建接口通常返回，查询接口可能省略
`object`	固定为 `video`
`model`	模型名称
`status`	任务状态
`progress`	任务进度，0-100
`seconds`	实际视频秒数
`video_url`	当前 Grok 任务完成后的 mp4 直链
`metadata.url`	兼容字段，部分通道或旧响应可能使用这个字段
`error`	失败时的错误信息

客户端建议每 5-10 秒轮询一次，直到 status=completed 或 status=failed。

状态值通常包括：

状态	说明
`queued`	已排队或处理中
`in_progress`	生成中
`completed`	已完成
`failed`	失败
`cancelled` / `canceled`	已取消
`expired`	已过期

6. 下载视频

6.1 使用平台代理下载

平台代理地址不会在查询响应中自动返回，但可以由 task_id 拼接：

https://api.pinniq.org/v1/videos/{task_id}/content

示例：

成功时返回：

HTTP 200
Content-Type: video/mp4

这个接口需要鉴权。调用者必须使用与任务归属用户匹配的 API Key。

6.2 使用查询响应里的直链下载

如果查询响应包含 video_url，也可以直接下载：

兼容建议：

优先读取 video_url。

如果没有，读取 metadata.url。

如果希望统一走平台鉴权下载，直接拼 /v1/videos/{task_id}/content。

7. 完整 Python 示例

下面脚本会：

创建视频任务。

轮询查询任务。

保存创建响应和最终响应。

优先用平台 /content 下载视频。

如果 /content 下载失败，再尝试 video_url 或 metadata.url。

运行示例：

图片生成视频：

8. 常见问题

创建接口会直接返回视频 URL 吗？

不会。创建接口只返回任务信息，例如 id / task_id / status / progress。

查询接口最终返回一个 URL 还是两个 URL？

当前 Grok 任务完成后，查询接口实测返回一个直链字段：video_url。

同时，平台还提供一个可拼接的代理下载地址：

https://api.pinniq.org/v1/videos/{task_id}/content

这个代理地址不是查询响应里的第二个 URL，而是由 task_id 拼接得到。

应该用 `video_url` 还是 `/content`？

两者都可以。推荐客户端同时兼容：

展示或简单下载：可以使用 video_url。

希望统一走 FriModel 鉴权和任务归属校验：使用 /content。

`/content` 返回 401 或 404 怎么办？

检查：

是否带了 Authorization: Bearer ...。

API Key 是否属于创建该任务的用户。

task_id 是否正确。

任务是否已经完成。

`/content` 返回的是什么？

成功时直接返回 mp4 文件流，不是 JSON：

Content-Type: video/mp4

失败时返回 JSON 错误对象：

{
  "error": {
    "message": "Task not found",
    "type": "invalid_request_error"
  }
}

9. 最小接入代码流程

伪代码：

create = POST /v1/videos
task_id = create.task_id or create.id

loop:
  task = GET /v1/videos/{task_id}
  if task.status == "completed":
    download GET /v1/videos/{task_id}/content with Authorization
    break
  if task.status == "failed":
    throw task.error
  sleep 5 seconds

最小 curl 流程：

Grok 接入指南

Grok 视频生成 API 开发手册#

1. 接入结论#

2. 支持模型#

3. 创建任务#

3.1 纯文字生成视频#

3.2 图片生成视频#

4. 创建任务参数#

5. 查询任务#

6. 下载视频#

6.1 使用平台代理下载#

6.2 使用查询响应里的直链下载#

7. 完整 Python 示例#

8. 常见问题#

创建接口会直接返回视频 URL 吗？#

查询接口最终返回一个 URL 还是两个 URL？#

应该用 video_url 还是 /content？#

/content 返回 401 或 404 怎么办？#

/content 返回的是什么？#

9. 最小接入代码流程#