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

更新时间：2026-08-03

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

API Base URL：https://kkflow.org
建议统一使用带 /v1 的路径。

鉴权

Authorization: Bearer <API_KEY>

POST 请求：

Content-Type: application/json

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

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
• 多供应商切换、导入配置后重启客户端生效

最短步骤

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

注意

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

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

二、常用模型

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

三、对话

Chat Completions

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

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

四、生图

文生图参数

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

resolution 说明

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

aspect_ratio 常见取值

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

关于 size

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

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

不要依赖 size 一定生效。

最小示例

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

完整示例（推荐）

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，再查询状态并下载。

场景与模型

注意：

• 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 不能混用。

主要参数

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

图生 vs 参考图

文生视频

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"
  }'

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

图生视频

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"
  }'

参考图生视频

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。

编辑视频

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 表示新增时长。

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 秒查询一次：

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

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

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

视频单价（参考）

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

六、推荐流程

七、常见错误

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