# 云枢 API Grok CLI 生图使用与计费避坑指南

更新日期：2026-08-03  
适用范围：通过 Grok CLI 使用云枢 API 的自然语言生图功能

## 使用前必读

> **重要计费提醒**
>
> 1. 生图和普通文字对话是两套计费：成功触发生图时按图片模型计费；没有触发生图时，仍可能按 `grok-4.5` 的文字 Token 计费。
> 2. 生图提示词必须明确包含“图片、图像、照片、海报、插画、图”等字样。不要只写“生成一个……”“帮我做一个……”或“画一个……”。
> 3. 提示词不明确时，Grok CLI 可能改用客户端自带的 `imagine` 工具。工具失败后如果自动重试，每次重试都可能再次请求 `grok-4.5` 并产生一笔新的文字费用。
> 4. 看到 `imagine` 失败、重复运行或长时间重试时，应立即按 `Esc` 或 `Ctrl+C` 停止。不要等待它无限重试，也不要马上重复提交相同提示词。
> 5. 一次只提交一个生图请求。没有确认上一条请求最终状态之前，不要重复回车、点击重试、开启第二个终端或在多个设备上同时提交。

当前系统不能保证自动识别所有含糊的自然语言。避免额外扣费最有效的方法，是使用本指南提供的固定提示词格式。

## 连接配置

在 Grok CLI 中添加云枢 API 模型时使用以下参数：

| 配置项 | 填写内容 |
| --- | --- |
| Base URL | `https://yunshuapi.wiki/grok-media/v1` |
| Model | `grok-4.5` |
| API Backend | `responses` |
| API Key | 您自己的云枢 API Key |
| 显示名称 | 可自定义，例如“云枢 Grok 媒体” |

注意事项：

- Base URL 必须完整包含 `/grok-media/v1`，不能只填写主域名，也不要自行改成其他路径。
- Grok CLI 中填写的模型是 `grok-4.5`。服务端在识别到明确生图指令后，才会转换为图片模型。
- 不要把 API Key 发给他人，也不要把包含 Key 的配置、终端截图或请求命令发到公开群聊。
- 本功能不要求安装额外 Skill、脚本或第三方插件。

## 推荐提示词格式

建议固定使用以下结构：

```text
请生成一张1K图片：[主体]，[风格]，[背景]，[光线或构图要求]
```

正确示例：

```text
请生成一张1K图片：白色背景上的红色传统剪纸作品，正面构图，细节清晰
```

```text
请生成一张图片：雨夜霓虹灯下的未来城市街道，电影感，横向构图
```

```text
请生成两张图片：一只坐在窗边的橘猫，温暖自然光，写实摄影风格
```

### 使用 Quality 高质量图片模型

普通提示词默认使用 `grok-imagine-image`。需要 Quality 时，必须在当前提示词中写出完整模型名：

```text
使用 grok-imagine-image-quality 生成一张2K图片：[主体]，[风格]，[背景]，[光线或构图要求]
```

示例：

```text
使用 grok-imagine-image-quality 生成一张2K图片：雨夜霓虹灯下的未来城市街道，写实电影感，横向构图，细节清晰，无文字、无水印
```

只写“高质量”“高清”或“2K”不会切换模型。完整模型名只控制当前这次生成；Grok CLI 配置中的 Model 仍保持 `grok-4.5`。Quality 和 2K 输出可能具有更高费用，提交前请查看控制台实时价格。

为了控制费用，首次尝试建议只生成一张。确认风格和构图后，再决定是否生成更多版本。

## 容易写错的提示词

以下写法不够明确，不建议使用：

| 不推荐写法 | 问题 | 推荐改法 |
| --- | --- | --- |
| `生成一个红色剪纸` | 没有明确说明生成图片 | `请生成一张图片：红色传统剪纸作品` |
| `画一只猫` | 可能未命中服务端图片识别 | `请生成一张图片：一只猫的插画` |
| `帮我做个头像` | “头像”不一定被识别为图片指令 | `请生成一张图片：社交账号头像，内容为……` |
| `做一个科技感封面` | 没有明确媒体类型 | `请生成一张海报图片：科技感封面，内容为……` |
| `再试一次` | 可能重复执行上一条付费请求 | 新建会话，重新写出完整且明确的提示词 |
| `多来几个` | 数量不明确，难以预估费用 | 明确写“一张、两张”等数量 |

不要依赖模型根据上下文猜测“这句话是在生图”。每次付费请求都应在当前消息中写清楚“数量 + 图片类型 + 具体内容”。

## 正确操作流程

1. 在提交前先完整写好提示词，并确认包含“图片、图像、照片、海报、插画、图”中的至少一个明确词语。
2. 确认生成数量。对费用不确定时，只写“一张”。
3. 建议为每次正式生图创建一个新会话，避免旧会话上下文越来越长，增加文字 Token 消耗。
4. 只提交一次，然后等待界面给出明确的成功或失败结果。
5. 成功后立即打开并下载图片。临时图片链接通常只保留约 15 分钟。
6. 在云枢 API 控制台核对消费记录，确认图片模型的请求次数与自己提交的次数一致。

## 哪些情况会导致多扣费

### 1. 含糊指令触发 `imagine` 自动重试

这是最需要注意的情况。

例如输入：

```text
生成一个红色剪纸
```

这句话没有明确写“图片”。服务端可能把它当作普通文字请求交给 `grok-4.5`。随后文字模型可能调用 Grok CLI 自带的 `imagine` 工具；如果工具失败并自动重试，就可能连续产生多条 `grok-4.5` 消费记录。

这种情况下，即使最终没有得到图片，之前已经完成的文字模型请求仍可能正常计费。

### 2. 失败后手动重复提交

请求超时、界面卡住或网络断开，不代表上游一定没有执行。立即再次回车、点击重试或重新输入相同提示词，可能产生第二次独立请求和第二笔费用。

正确处理方式是先停止当前运行，再到控制台查看是否已经出现消费记录。无法确认时，请先联系云枢 API 客服，不要连续试错。

### 3. 同时打开多个终端或设备

在两个 Grok CLI 窗口、两台设备或多个自动化任务中同时提交相同内容，可能被视为多个独立请求。每个真正执行的请求都可能单独计费。

### 4. 请求多张图片

“生成两张、三张、四张图片”会按实际图片数量计费。这不是重复扣费，而是正常的按张计费。测试提示词时建议从一张开始。

### 5. 在长会话中反复修改提示词

普通文字请求按 Token 计费。会话越长，每轮可能携带的历史上下文越多；连续说“换一种”“再试一次”“还是不对”可能同时增加文字费用，并有机会再次触发生图。

建议把修改后的完整要求整理好，再新建会话提交一次。

### 6. 为了恢复过期链接重新生图

图片临时链接过期后，重新提交生图提示词会创建一张新的付费图片，并不是免费恢复原链接。图片生成成功后应尽快下载到本地保存。

### 7. 会话标题辅助请求

云枢媒体入口已经把 Grok CLI 的 `session_title` 会话标题请求改为服务端本地处理，不再调用 `grok-4.5`，也不应产生额外的标题费用。如果仍出现非预期的连续 `grok-4.5` 记录，应优先检查提示词是否未命中生图桥、客户端是否重试，或是否还有其他普通文字请求。

## 如何判断扣的是什么费用

在云枢 API 控制台查看消费记录中的模型名称：

| 记录中的模型 | 通常代表 |
| --- | --- |
| `grok-imagine-image` | 实际图片生成费用 |
| `grok-4.5` | 普通文字、未命中生图桥的请求或失败后的重试产生的文字费用 |

还要同时查看请求时间和记录数量：

- 只提交一次，却连续出现多条时间接近的 `grok-4.5` 记录：通常是工具调用或自动重试。
- 出现多条 `grok-imagine-image` 记录：通常代表发生了多次独立的图片生成请求。
- 只有一条 `grok-imagine-image` 记录但费用较高：可能是该请求明确要求生成多张图片，应结合图片数量和当时价格核对。
- 没有图片模型记录、只有文字模型记录：说明生图桥大概率没有被触发，最终也可能没有生成图片。

最终扣费以云枢 API 控制台显示的实际消费记录和当时生效的价格为准。

## 出现异常时立即这样处理

1. 按 `Esc` 取消当前工具运行；无效时使用 `Ctrl+C` 终止 Grok CLI。
2. 不要点击重试，也不要输入“再试一次”。
3. 不要在另一个窗口重复提交相同提示词。
4. 记录异常发生时间、所选模型、提示词和界面错误信息。
5. 到云枢 API 控制台查看对应时段的消费记录，并区分 `grok-4.5` 与 `grok-imagine-image`。
6. 联系客服时提供消费记录截图和大致时间，但必须遮住完整 API Key、Authorization 请求头及其他账号隐私。

## 当前功能边界

- 本指南适用于 Grok CLI 通过 `https://yunshuapi.wiki/grok-media/v1` 进行自然语言生图。
- 当前同一个 Grok CLI 自然语言入口已经支持直接文生视频，连接配置仍为 `grok-4.5`、`responses` 和 `/grok-media/v1`。
- 生视频必须使用“生成视频：”开头的固定格式，并明确时长和分辨率。完整说明见[《云枢 API Grok CLI 生视频使用与计费避坑指南》](./云枢API-Grok-CLI生视频使用与计费避坑指南.md)或文档网站的视频章节。
- 图片可能以 JPEG、PNG 或其他受支持格式返回，实际格式以下载文件为准。
- 临时资源链接不是永久网盘，请及时下载和备份。

## 提交前检查清单

每次生图前请确认：

- [ ] Base URL 是 `https://yunshuapi.wiki/grok-media/v1`
- [ ] Grok CLI 模型是 `grok-4.5`
- [ ] 提示词明确包含“图片、图像、照片、海报、插画、图”等词语
- [ ] 已写明生成数量，测试时优先一张
- [ ] 已了解本次请求会产生费用
- [ ] 当前没有其他窗口或设备提交相同请求
- [ ] 只会提交一次，不会因等待而重复回车
- [ ] 如果出现 `imagine` 失败或自动重试，会立即取消

---

云枢 API：<https://yunshuapi.wiki/>  
请妥善保管 API Key。任何客服人员都不应要求您发送完整 Key。