Grok API 使用文档，包含对话、图片、视频

更新时间：2026-08-03

通过 KKFlow 使用 Grok 对话、生图与视频能力。

API Base URL：https://kkflow.org

建议统一使用带 /v1 的路径。

鉴权

http 复制代码

Authorization: Bearer <API_KEY>

POST 请求：

http 复制代码

Content-Type: application/json

请使用平台分配的 Grok 分组 API Key。可先确认可用模型：

bash 复制代码

curl "https://kkflow.org/v1/models" \
  -H "Authorization: Bearer 你的API密钥"

一、用 CC Switch 自动接入 Grok（推荐）

最新版 CC Switch 已支持 Grok 自动接入 ，可统一管理 Grok Build（Grok CLI）等客户端配置，无需手改配置文件。

适用场景

在本机用 Grok Build 写代码 / Agent
通过 KKFlow 等中转的 Grok 分组 Key，一键写入 ~/.grok/config.toml
多供应商切换、导入配置后重启客户端生效

最短步骤

安装本机 Grok Build CLI （若尚未安装）
- Windows：irm https://x.ai/cli/install.ps1 | iex
- macOS / Linux：curl -fsSL https://x.ai/cli/install.sh | bash
安装并打开 最新版 CC Switch
在应用列表中进入 Grok Build（或 Grok）相关页
添加 / 导入供应商：
- Base URL ：https://kkflow.org/v1
- API Key：平台分配的 Grok 分组密钥
- 模型：如 grok-4.5 或 grok-build-0.1（以 /v1/models 与后台为准）
KKFlow 后台提供「导入到 CC Switch / CCS」入口，可直接导入，少填手动项
启用该配置后，完全退出并重开 Grok Build / 终端，再执行 grok

注意

必须使用 Grok 分组 Key，不要用其它业务分组的 Key
CC Switch 改的是本地配置；已在运行的进程不会自动热加载，请重启客户端
对话 / 生图 / 视频 HTTP 接口仍可直接调本文后续章节，不依赖 CC Switch

下载：https://github.com/farion1231/cc-switch/releases

二、常用模型

类型	模型	说明
对话	`grok-4.5`	旗舰，默认推荐
对话	`grok-4.3`	长上下文
对话	`grok-build-0.1`	编程 / Agent
生图	`grok-imagine-image-quality`	高质量生图（推荐）
生图	`grok-imagine-image`	标准生图
改图	`grok-imagine-edit`	图片编辑
视频	`grok-imagine-video`	文生视频、参考图视频、编辑、延长
视频	`grok-imagine-video-1.5`	图生视频、参考图视频；单图 `image` 模式可 1080p

别名（以网关实际映射为准）：grok / grok-latest → grok-4.5；grok-build → grok-build-0.1；grok-imagine 生图时常为 quality。

三、对话

接口	方法
`/v1/chat/completions`	POST
`/v1/responses`	POST

Chat Completions

bash 复制代码

curl "https://kkflow.org/v1/chat/completions" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "用三句话介绍你自己"}
    ]
  }'

流式：设置 "stream": true。

Responses

bash 复制代码

curl "https://kkflow.org/v1/responses" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "写一个 Python 函数，打印 Hello"
  }'

场景	推荐模型
默认对话	`grok-4.5`
写代码 / Agent	`grok-4.5` 或 `grok-build-0.1`
长文档	`grok-4.3`

四、生图

接口	方法
`/v1/images/generations`	POST
`/v1/images/edits`	POST

文生图参数

最少只需 model + prompt。常用完整参数如下：

参数	必填	说明
`model`	是	推荐 `grok-imagine-image-quality`；也可用 `grok-imagine-image`
`prompt`	是	画面描述
`n`	否	同一次请求生成张数，默认 `1`
`aspect_ratio`	否	画幅比例，控制宽高形状
`resolution`	否	清晰度档位：仅 `1k` 或 `2k`（不支持 4k）
`response_format`	否	返回形式：`url`（默认）或 `b64_json`

`resolution` 说明

值	说明
`1k`	约 1024 长边，更快、更省
`2k`	约 2048 长边，更清晰（当前最高）
`4k` / `4K`	不支持。Grok Imagine 生图官方无 4k 档

需要更高清时请使用 "resolution": "2k"，不要传 4k。

`aspect_ratio` 常见取值

比例	常见用途
`1:1`	方图、头像、封面
`16:9` / `9:16`	横屏视频参考 / 竖屏
`4:3` / `3:4`	演示、人像
`3:2` / `2:3`	摄影构图
`2:1` / `1:2`	横幅 / 竖幅
`19.5:9` / `9:19.5`、`20:9` / `9:20`	超宽 / 全面屏
`auto`	由模型按提示词自行选择

以当前上游实际支持列表为准。

关于 `size`

部分客户端会传类似 2048x1152 的 size 字段。经 KKFlow / Grok 通路时，size 不一定会转发给上游（可能仅用于本地计费档位）。请优先使用：

aspect_ratio 控制形状
resolution（1k / 2k）控制清晰度档

不要依赖 size 一定生效。

最小示例

bash 复制代码

curl "https://kkflow.org/v1/images/generations" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "电影级写实，雨夜霓虹街道，红伞与黑风衣"
  }'

完整示例（推荐）

bash 复制代码

curl "https://kkflow.org/v1/images/generations" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "电影级写实，雨夜霓虹街道，红伞与黑风衣",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "response_format": "b64_json"
  }'

响应

response_format 为 url 或不填：常见 data[].url（链接可能有时效，请及时下载）
response_format 为 b64_json：常见 data[].b64_json，解码后保存为图片文件

改图说明

路径：POST /v1/images/edits
模型：grok-imagine-edit（或分组映射后的等价模型）
除 model、prompt 外，需提供输入图片（公网 URL、data URL 或 multipart，以平台当前支持为准）
单图编辑时，输出比例通常跟随输入图

五、视频

视频为异步任务 ：先提交取得 request_id，再查询状态并下载。

用途	方法	路径
生成	POST	`/v1/videos/generations`
编辑	POST	`/v1/videos/edits`
延长	POST	`/v1/videos/extensions`
查询	GET	`/v1/videos/{request_id}`
下载	GET	`/v1/videos/{request_id}/content`

场景与模型

场景	模型	时长	分辨率
文生视频	`grok-imagine-video`	1-15 秒	480p、720p
图生视频	`grok-imagine-video-1.5`	1-15 秒	480p、720p、1080p
参考图生视频	`grok-imagine-video`	1-10 秒	480p、720p；最多 7 张参考图
参考图生视频	`grok-imagine-video-1.5`	1-15 秒	480p、720p；最多 7 张参考图
编辑	`grok-imagine-video`	继承输入，输入最长 8.7 秒	最高 720p
延长	`grok-imagine-video`	新增 2-10 秒	最高 720p

注意：

1080p 仅支持 grok-imagine-video-1.5 的单图 image 模式；reference_images 模式最高 720p。
reference_images 可使用 grok-imagine-video 或 grok-imagine-video-1.5。基础模型最长 10 秒，1.5 实测最长 15 秒。
reference_images 最多 7 张；8 张会被上游拒绝。
编辑、延长仅支持 grok-imagine-video。
image 与 reference_images 不能混用。

主要参数

参数	适用	说明
`model`	全部	必填
`prompt`	全部	必填
`duration`	生成、延长	参考图基础模型 1-10 秒，参考图 `1.5` 为 1-15 秒；其他见上表
`resolution`	生成	`480p` / `720p`；1080p 仅支持 `1.5 + image`
`aspect_ratio`	生成	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`
`image`	图生	`{ "url": "..." }`
`reference_images`	参考图	1-7 个 `{ "url": "..." }`
`video`	编辑、延长	`{ "url": "..." }`

媒体支持公网 HTTPS 或 data URL。下载地址 /content 需要 API Key，不能直接当作 video.url 再提交。

图生 vs 参考图

	图生视频	参考图生视频
字段	`image`	`reference_images`
第一帧	输入图	不固定
数量	1	1-7
推荐模型	`grok-imagine-video-1.5`	1-10 秒用 `grok-imagine-video`；11-15 秒用 `grok-imagine-video-1.5`
分辨率	480p、720p、1080p	480p、720p

文生视频

bash 复制代码

curl -X POST "https://kkflow.org/v1/videos/generations" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "电影级写实，海边日落，镜头缓慢向前，海浪自然起伏",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

json 复制代码

{ "request_id": "video-request-123" }

图生视频

bash 复制代码

curl -X POST "https://kkflow.org/v1/videos/generations" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "保持人物身份一致，自然回眸微笑，镜头缓慢推近",
    "image": { "url": "https://example.com/source.png" },
    "duration": 8,
    "resolution": "1080p"
  }'

参考图生视频

bash 复制代码

curl -X POST "https://kkflow.org/v1/videos/generations" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "参考图片中的人物与服装，走上海边木栈道，镜头平滑跟随",
    "reference_images": [
      { "url": "https://example.com/person.png" },
      { "url": "https://example.com/outfit.png" }
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

提示词建议精简，过长可能导致失败。

上例使用基础模型，适合 1-10 秒参考图视频。需要生成 11-15 秒时，将 model 改为 grok-imagine-video-1.5；即使使用 1.5，参考图模式也只能选择 480p 或 720p，不能选择 1080p。

编辑视频

bash 复制代码

curl -X POST "https://kkflow.org/v1/videos/edits" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "把天气改成下雪，其余保持不变",
    "video": { "url": "https://example.com/input.mp4" }
  }'

延长视频

duration 表示新增时长。

bash 复制代码

curl -X POST "https://kkflow.org/v1/videos/extensions" \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "从最后一帧无缝继续，人物向前走两步",
    "video": { "url": "https://example.com/input.mp4" },
    "duration": 6
  }'

查询与下载

建议每 3～5 秒查询一次：

bash 复制代码

curl "https://kkflow.org/v1/videos/video-request-123" \
  -H "Authorization: Bearer 你的API密钥"

状态	含义
`pending`	排队或生成中
`done`	完成
`failed`	失败
`expired`	过期

bash 复制代码

curl -L "https://kkflow.org/v1/videos/video-request-123/content" \
  -H "Authorization: Bearer 你的API密钥" \
  -o output.mp4

请使用同一 API Key 查询和下载，完成后及时保存。

视频单价（参考）

模型	480p	720p	1080p
`grok-imagine-video`	$0.05/s	$0.07/s	---
`grok-imagine-video-1.5`	$0.08/s	$0.14/s	$0.25/s

2026-08-03 的 grok-imagine-video-1.5 实测账单中，每张 image / reference_images 输入图片另增加约 $0.01；该观察不直接外推到基础视频模型。实际费用以平台账单为准。

六、推荐流程

目标	做法
本机 Grok Build 写代码	最新版 CC Switch 自动接入 + `grok-4.5` / `grok-build-0.1`
对话 API	`grok-4.5` + `/v1/chat/completions`
先图后视频（多参考）	生图 → `reference_images`；1-10 秒用 `grok-imagine-video`，11-15 秒用 `grok-imagine-video-1.5`
单图驱动视频	图片 + `image` + `grok-imagine-video-1.5`
快速文生视频	`grok-imagine-video` 文生 → 轮询 → 下载

七、常见错误

HTTP	常见原因
400	缺 model、参数组合不支持、媒体不合规、提示词过长；如参考图超过 7 张、`1.5` 参考图使用 1080p、时长超过 15 秒、混用 `image` 与 `reference_images`
401	API Key 无效
403	无权限或内容审核
404	路径错误、任务不存在、或 Key 无法使用该模型
413	data URL 过大
422	上游可解析请求但素材或参数不符合当前模式；基础模型参考图超过 10 秒时可能出现
429	请求过频或限流
503	暂时无可用上游

视频排查优先检查：参考图是否超过 7 张；基础模型参考图是否超过 10 秒、1.5 参考图是否超过 15 秒或误传 1080p；是否混用 image 与 reference_images；编辑/延长是否误用 1.5；编辑输入是否超过 8.7 秒；延长输入是否为 2-15 秒；MP4 是否可解码；公网 URL 是否可访问。

Grok API 使用文档，包含对话、图片、视频

鉴权

一、用 CC Switch 自动接入 Grok（推荐）

适用场景

最短步骤

注意

二、常用模型

三、对话

Chat Completions

Responses

四、生图

文生图参数

resolution 说明

aspect_ratio 常见取值

关于 size

最小示例

完整示例（推荐）

响应

改图说明

五、视频

场景与模型

主要参数

图生 vs 参考图

文生视频

图生视频

参考图生视频

编辑视频

延长视频

查询与下载

视频单价（参考）

六、推荐流程

七、常见错误

`resolution` 说明

`aspect_ratio` 常见取值

关于 `size`