Frimdel Grok Video API 接入指南

本文面向需要通过 Pinniq 接入 Grok Video 的服务端开发者，介绍模型能力、鉴权、请求参数、异步任务流程、结果下载、错误处理和计费规则。

支持模型：

grok-imagine-video
grok-imagine-video-1.5-preview

Base URL：

https://api.pinniq.org

1. 快速开始

1.1 环境变量

1.2 创建任务

成功后会返回公开任务 ID：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1784600000
}

1.3 查询任务

1.4 下载视频

2. 基础约定

2.1 鉴权

所有接口使用 Bearer Token：

API Key 应只保存在服务端，不应写入浏览器代码、移动端安装包、公开仓库或业务日志。

2.2 接口列表

功能	方法	路径
查询可用模型	`GET`	`/v1/models`
创建视频任务	`POST`	`/v1/videos`
查询任务状态	`GET`	`/v1/videos/{task_id}`
获取视频内容	`GET`	`/v1/videos/{task_id}/content`

Frimdel 当前使用 /v1/videos 创建任务，不提供 xAI 原生的 /v1/videos/generations 路径。

2.3 请求类型

支持：

application/json

multipart/form-data

multipart 请求应由 HTTP 客户端自动生成 boundary，不要手工设置完整的 Content-Type。

3. 模型能力

3.1 能力矩阵

能力	`grok-imagine-video`	`grok-imagine-video-1.5-preview`
文生视频	支持	不支持
单图图生视频	支持	支持，必须提供图片
多参考图视频	支持	不支持
普通生成时长	1～15 秒	1～15 秒
参考图最大数量	7 张	不适用
参考图模式最大时长	10 秒	不适用
支持分辨率	480p、720p	480p、720p、1080p
支持画幅	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`	同左
21:9	不支持	不支持

3.2 Grok Imagine Video 1.0

模型 ID：

grok-imagine-video

适用于：

纯文本生成视频。

使用一张图片作为首帧生成视频。

使用多张图片引导人物、商品、服装或视觉风格。

1.0 不支持 1080p，请使用 480p 或 720p。

3.3 Grok Imagine Video 1.5

Frimdel 模型 ID：

grok-imagine-video-1.5-preview

xAI 官方主模型名和别名：

grok-imagine-video-1.5
grok-imagine-video-1.5-preview
grok-imagine-video-1.5-2026-05-30

1.5 当前仅支持图生视频：

必须提供一张输入图片。

不支持文生视频。

不支持多参考图模式。

支持 1080p 图生视频。

4. 创建视频任务

4.1 请求参数

参数	类型	必填	说明
`model`	string	是	视频模型 ID
`prompt`	string	是	视频生成提示词，不能为空
`duration`	integer/string	否	生成时长，范围 1～15 秒
`aspect_ratio`	string	否	xAI 官方画幅字段
`ratio`	string	否	Frimdel 兼容画幅字段，与 `aspect_ratio` 二选一
`resolution`	string	否	输出分辨率档位
`image`	string	条件必填	单图 URL 或 Base64 Data URI；1.5 必填
`reference_images`	object[]	条件必填	xAI 官方多参考图字段，仅 1.0 支持
`images`	string[]	条件必填	Frimdel 多参考图兼容字段
`mode`	string	否	`text-to-video`、`image-to-video` 或 `reference-to-video`
`metadata`	object	否	扩展数据；常用参数优先使用顶层字段

4.2 画幅

允许值：

1:1
16:9
9:16
4:3
3:4
3:2
2:3

不支持 21:9。

推荐使用 xAI 官方字段：

{
  "aspect_ratio": "9:16"
}

Frimdel 兼容字段也可使用：

{
  "ratio": "9:16"
}

不要同时传 aspect_ratio 和 ratio。

4.3 分辨率

模型	480p	720p	1080p
`grok-imagine-video`	支持	支持	不支持
`grok-imagine-video-1.5-preview`	支持	支持	支持

示例：

{
  "resolution": "720p"
}

分辨率是质量档位，实际像素尺寸可能因画幅和编码对齐略有差异。例如 1.5 的 1080p、9:16 输出可能接近 1072x1904，而不是严格的 1080x1920。

4.4 时长

{
  "duration": 5
}

允许范围：1～15 秒。

多参考图模式最长 10 秒。

5. 文生视频

仅支持：

grok-imagine-video

不要使用 1.5 发起文生视频请求，否则会返回模型不支持文本生成视频的错误。

6. 单图图生视频

支持：

grok-imagine-video
grok-imagine-video-1.5-preview

6.1 图片 URL

Frimdel JSON 接口中，image 直接传字符串 URL：

图片 URL 要求：

可被 Frimdel 和上游服务直接访问。

不依赖登录 Cookie。

签名 URL 的有效期应覆盖排队和生成时间。

不要使用 localhost 或局域网地址。

6.2 Base64 Data URI

{
  "model": "grok-imagine-video-1.5-preview",
  "prompt": "Add subtle natural motion while preserving the main subject",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "480p"
}

Base64 会使请求体积增加约三分之一。大图优先使用 HTTPS URL 或 multipart 上传。

6.3 Frimdel JSON 兼容说明

xAI 原生 REST 示例使用对象形式：

{
  "image": {
    "url": "https://example.com/input.jpg"
  }
}

Frimdel 当前 JSON 接口要求 image 为字符串：

{
  "image": "https://example.com/input.jpg"
}

如果需要最大程度兼容 Frimdel，请使用字符串 URL 或 Data URI。

7. 多参考图视频

仅支持：

grok-imagine-video

参考图不会固定成为视频首帧，而是用于引导人物、商品、服装或视觉风格。

限制：

最多 7 张参考图。

最长 10 秒。

prompt 不能为空。

1.5 不支持此模式。

7.1 xAI 官方写法

7.2 Frimdel 兼容写法

{
  "model": "grok-imagine-video",
  "mode": "reference-to-video",
  "prompt": "Use both images as visual references",
  "images": [
    "https://example.com/reference-1.jpg",
    "https://example.com/reference-2.jpg"
  ],
  "duration": 10,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

8. multipart/form-data 上传

multipart 适合直接上传本地图片。

8.1 cURL

8.2 Node.js FormData

不要手工设置 Content-Type: multipart/form-data，客户端需要自动附加 boundary。

9. 创建任务响应

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video-1.5-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1784600000
}

字段	类型	说明
`id`	string	Frimdel 公开任务 ID，推荐使用
`task_id`	string	兼容字段，当前通常与 `id` 相同
`object`	string	固定为 `video`
`model`	string	请求使用的模型
`status`	string	初始通常为 `queued`
`progress`	integer	0～100
`created_at`	integer	Unix 秒级时间戳

请持久化 id。Frimdel 返回的是平台公开任务 ID，不是上游 xAI 原始请求 ID。

响应头可能包含：

X-Oneapi-Request-Id 可用于问题排查和技术支持。

10. 查询任务状态

10.1 状态枚举

状态	说明	是否终态
`queued`	已进入队列	否
`in_progress`	正在生成	否
`completed`	生成成功	是
`failed`	生成失败	是
`unknown`	暂未映射到明确状态	否

如果短暂出现 unknown，应继续轮询，不要立即判定任务失败。

10.2 完成响应

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video-1.5-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1784600000,
  "completed_at": 1784600088,
  "seconds": "5",
  "metadata": {
    "url": "https://vidgen.x.ai/.../video.mp4"
  }
}

metadata.url 是上游托管地址，可能具有时效性。建议完成后立即转存到自己的对象存储。

10.3 失败响应

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "grok-imagine-video-1.5-preview",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "task_failed",
    "message": "Video generation failed"
  }
}

11. 轮询示例

11.1 Bash

11.2 轮询策略

推荐间隔：3～5 秒。

推荐总超时：10～15 分钟。

completed 或 failed 后立即停止。

unknown 继续轮询。

不建议高频轮询。

12. 下载与存储

12.1 使用 Frimdel 内容接口

典型响应：

12.2 使用结果 URL

12.3 输出格式

当前视频通常为：

MP4 容器

H.264 主视频

24 fps

yuv420p

AAC 双声道音轨

可能包含 MJPEG 封面流

即使请求没有显式音频参数，结果也可能包含声音。转码时不要遗漏音轨。

13. Python 完整示例

14. Node.js 完整示例

15. 参数校验规则

建议在调用 Frimdel 前完成本地校验：

场景	校验规则
1.0 文生视频	不传图片；分辨率只能是 480p、720p
1.0 单图图生视频	传一张 `image`
1.0 多参考图	最多 7 张；时长不超过 10 秒
1.5 图生视频	必须传一张 `image`
1.5 文生视频	不支持
普通时长	1～15 秒
画幅	只允许 7 种官方比例
21:9	不支持
1.0 1080p	不支持

16. 错误处理

16.1 Frimdel 错误结构

{
  "code": "fail_to_fetch_task",
  "message": "error details",
  "data": null
}

部分上游错误会作为 JSON 字符串嵌套在 message 中：

{
  "code": "fail_to_fetch_task",
  "message": "{\"code\":\"invalid-argument\",\"error\":\"Duration must be between 1 and 15 seconds\"}",
  "data": null
}

客户端可以尝试对 message 再解析一次 JSON，同时保留普通字符串兼容。

16.2 常见错误

HTTP	场景	处理建议
400	JSON `image` 使用对象	改为 URL 或 Data URI 字符串
400	1.5 没有图片	提供 `image` 或 multipart 文件
400	时长超过 15 秒	使用 1～15 秒
400	1.0 请求 1080p	改用 480p、720p，或使用 1.5 图生视频
401	API Key 无效	检查 Bearer Token
404	使用 `/v1/videos/generations`	改为 `/v1/videos`
422	画幅不受支持	使用官方支持的 7 种比例
429	平台或上游限流	延迟并指数退避
5xx	临时服务错误	有上限地重试

17. 重试与幂等

视频任务会产生实际费用，不要无限重试创建请求。

4xx 参数错误不重试。

429 使用指数退避。

5xx 可有限重试。

POST 已发出但响应丢失时，避免直接无限重发。

业务侧保存本地请求 ID 和 Frimdel task_id。

当前不要假设创建接口支持通用幂等键。

18. 计费说明

18.1 xAI 官方价格参考

以下为 xAI 官方直连价格参考，不代表 Frimdel 最终售价：

模型	输入	480p 输出	720p 输出	1080p 输出
`grok-imagine-video`	图片 `$0.002/张`；视频 `$0.01/秒`	`$0.05/秒`	`$0.07/秒`	不支持
`grok-imagine-video-1.5`	图片 `$0.01/张`	`$0.08/秒`	`$0.14/秒`	`$0.25/秒`

18.2 Frimdel 计费

Frimdel 实际扣费以账户分组、模型价格和平台计费配置为准。

创建响应可能返回：

说明生成时长会进入异步任务计费参数。不要直接用 xAI 官方美元价格推算 Frimdel 账户扣费。

19. 生产接入建议

19.1 提示词

建议包含：

主体

动作

镜头运动

光线

风格

需要保持稳定的元素

示例：

保持商品形状、Logo 和包装文字稳定，镜头从正面缓慢环绕到右侧 30 度，柔和高光在玻璃表面移动，背景轻微虚化，高端商业广告质感，不出现额外物体。

19.2 任务存储

建议保存：

本地业务请求 ID

Frimdel task_id

模型、提示词摘要和输入方式

时长、分辨率和画幅

当前状态和进度

创建、最后轮询和完成时间

错误码和 X-Oneapi-Request-Id

转存后的永久视频 URL

19.3 结果验收

如果业务对宽高、时长或编码有硬性要求，下载后使用 ffprobe 验证：

19.4 安全

不接受用户提交内网图片 URL。

对输入图片执行类型和大小检查。

不在日志中记录完整 Base64。

下载结果时设置超时和体积限制。

API Key 只保存在服务端。

20. 对接检查清单

Base URL 使用 https://api.pinniq.org。

使用 Bearer Token 鉴权。

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

JSON 单图使用字符串 image。

多参考图使用 reference_images，最多 7 张。

1.5 始终提供图片。

时长限制在 1～15 秒。

参考图模式不超过 10 秒。

1.0 只使用 480p、720p。

1080p 只用于 1.5 图生视频。

不使用 21:9。

每 3～5 秒轮询任务。

unknown 状态继续轮询。

完成后及时下载并转存。

不记录或下发 API Key。

21. xAI 官方资料

Grok Imagine Video 1.5 模型说明

Grok Imagine Video 1.0 模型说明

xAI Video Generation

xAI Image-to-Video

xAI Reference-to-Video

Grok Video 1.0/1.5接入指南

Frimdel Grok Video API 接入指南#

1. 快速开始#

1.1 环境变量#

1.2 创建任务#

1.3 查询任务#

1.4 下载视频#

2. 基础约定#

2.1 鉴权#

2.2 接口列表#

2.3 请求类型#

3. 模型能力#

3.1 能力矩阵#

3.2 Grok Imagine Video 1.0#

3.3 Grok Imagine Video 1.5#

4. 创建视频任务#

4.1 请求参数#

4.2 画幅#

4.3 分辨率#

4.4 时长#

5. 文生视频#

6. 单图图生视频#

6.1 图片 URL#

6.2 Base64 Data URI#

6.3 Frimdel JSON 兼容说明#

7. 多参考图视频#

7.1 xAI 官方写法#

7.2 Frimdel 兼容写法#

8. multipart/form-data 上传#

8.1 cURL#

8.2 Node.js FormData#

9. 创建任务响应#

10. 查询任务状态#

10.1 状态枚举#

10.2 完成响应#

10.3 失败响应#

11. 轮询示例#

11.1 Bash#

11.2 轮询策略#

12. 下载与存储#

12.1 使用 Frimdel 内容接口#

12.2 使用结果 URL#

12.3 输出格式#

13. Python 完整示例#

14. Node.js 完整示例#

15. 参数校验规则#

16. 错误处理#

16.1 Frimdel 错误结构#

16.2 常见错误#

17. 重试与幂等#

18. 计费说明#

18.1 xAI 官方价格参考#

18.2 Frimdel 计费#

19. 生产接入建议#

19.1 提示词#

19.2 任务存储#

19.3 结果验收#

19.4 安全#

20. 对接检查清单#

21. xAI 官方资料#