X.AI 绘画（Grok 图像生成） - 数字先锋API文档

# Grok Imagine 图像生成 API 对接文档

> **用途**：第三方软件 / 自有应用对接「Grok Imagine 图像生成」能力（grok-imagine-image-2.0）

接口路径 `/v1/images/generations` 绘画接口（同步返回，秒级出图）

---

## 1. 快速开始

### 1.1 生成一张图片（同步，几秒内返回图片 URL）

```bash
curl https://api.cxsee.com/v1/images/generations \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "一只橘猫坐在窗台上，阳光洒进来，高清写实",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'
```

返回（可直接打开的图片 URL）：

```json
{
  "created": 1788763101,
  "data": [
    {
      "revised_prompt": "一只橘猫……",
      "url": "https://your-cdn.example.com/output/xxx.jpeg"
    }
  ],
  "model": "grok-imagine-image-2.0",
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}
```

---

## 2. 鉴权方式

所有接口使用 **API 令牌**（Bearer Token）鉴权：

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 兼容 Header | `x-api-key: <API 令牌>` / `api-key: <API 令牌>` |
| 令牌获取 | 登录控制台 →「令牌」页面创建；或注册 / OAuth / 微信登录后自动生成的默认密钥 |
| 内容类型 | `Content-Type: application/json` |

> 令牌以 `sk-` 开头。未认证或令牌失效返回 `401`。

**Base URL：`https://api.cxsee.com`**

---

## 3. 接口总览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/v1/images/generations` | 图像生成（**同步**返回结果） |

---

## 4. 图像生成（同步）

### 4.1 请求

```
POST /v1/images/generations
```

#### 请求体参数（JSON）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | **`grok-imagine-image-2.0`** |
| `prompt` | string | ✅ | 描述你要生成的画面，越具体效果越好（可含 <br> 分段） |
| `aspect_ratio` | string | 否 | 画面宽高比，如 `"1:1"` / `"3:4"` / `"4:3"` / `"16:9"` / `"9:16"`。默认参考模型策略 |
| `resolution` | string | 否 | 清晰度：`"1k"`（默认）或 `"2k"`。决定计费档位 |
| `size` | string | 否 | 像素尺寸写法（长边自动归档），兼容传入如 `"1024x1024"`、`"1792x1024"`；与 `resolution` 等价，二选一即可 |
| `n` | integer | 否 | 生成张数，**1~4**。默认 1。**按张计费**（见第 5 节） |
| `response_format` | string | 否 | `"url"`（默认）返回图片链接；`"b64_json"` 返回 base64 编码数据 |
| `quality` | string | 否 | 质量档（可选，配合模型支持程度） |
| `revised_prompt` 开关 | boolean/string | 否 | 是否需要返回 `revised_prompt` 修订文案 |

**分辨率 ↔ 计费档位对照**（长边判定）：

| `resolution` | 像素尺寸参考（长边≤） | 档位 |
|---|---|---|
| `1k` / `1024x1024` | ≤ 1792 | **1K** |
| `2k` / `2048x2048` | ≤ 3072 | **2K** |

> `resolution` 或像素 `size` 平台均归一为 1K / 2K 档位计费，不会再报 `size=<nil>` 规格错误。

### 4.2 同步出图示例（多图 + URL）

```bash
curl -X POST https://api.cxsee.com/v1/images/generations \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "画一只猫",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "n": 2,
    "response_format": "url"
  }'
```

返回 `data` 数组长度 = `n`，每项含 `url`（与 `revised_prompt`）。

### 4.3 返回 b64_json（base64 编码图片）

把 `response_format` 设为 `"b64_json"`，返回的 `data[]` 每项为 `b64_json` 字段（base64 字符串），需自行解码为图片文件保存。

```bash
curl -X POST https://api.cxsee.com/v1/images/generations \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "水墨风格的西湖",
    "aspect_ratio": "4:3",
    "resolution": "1k",
    "n": 1,
    "response_format": "b64_json"
  }' > resp.json
# 用 jq + base64 解码落盘
cat resp.json | jq -r '.data[0].b64_json' | base64 -d > output.jpeg
```

### 4.4 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `created` | int | 生成时间（Unix 秒） |
| `data[].url` | string | （`url` 模式）图片可直接访问/引用的链接 |
| `data[].b64_json` | string | （`b64_json` 模式）base64 编码的图片数据 |
| `data[].revised_prompt` | string | 模型润色后的提示词原文 |
| `model` | string | 实际使用的模型名 |
| `usage` | object | 图片任务 tokens 恒为 0，不计 token |

> `data[]` 数量与请求的 `n` 一致；余额不足、路径鉴权失败会返回带 `error` 的错误响应与对应 HTTP 状态码。

---

## 5. 计费说明（重要）

Grok Imagine 图片**按「档位 × 张数」固定价计费**（`size_fixed`，非按 token）。每张：

| 分辨率档位 | 单价（USD / 张） |
|---|---|
| 1K | **$0.24** |
| 2K | **$0.32** |

- 一次请求 `n` 张 → 费用 = 档位单价 × `n`
- 例：1K 生成 2 张 = $0.24 × 2 = **$0.48**
- `1K` 与基础档为最常用组合；`2K` 出图更高清但对上游耗时更长
- 计费成功后可在控制台 →「用量日志」查看本次扣费明细（按模型 + 消费）

> 平台展示金额以美元计（`$1 = 500000 quota`，即 1K 单张 = 120000 quota）。请确保令牌余额足够覆盖整批 `n` 张费用，否则提交可能失败或被拒。

---

## 6. 使用建议与限制

- **提示词技巧**：正向描述画面主体、构图、光线、风格；需要时用 `<br>` 或换行让 Grok 分段理解。
- **出图速度**：Grok Imagine 通常秒级返回；大幅面 2K 或高 `n` 会略慢，请合理设置客户端超时（建议 ≥ 120s）。
- **内容安全**：请遵守平台内容合规条款，勿提交违规 / 版权敏感 prompt。
- **结果转存**：`url` 模式返回的图片链接为上游输出地址，若需长期引用建议自行转存到 OSS / CDN（如平台七牛转存），避免链接失效。
- **失败处理**：返回非 200（如 `429` 限流 / `502` 上游抖动 / `400` 参数错）时，可对幂等可重试错误做轻量退避重试；`4xx` 参数/鉴权错误请先检查入参与令牌。

---

## 7. 各语言示例

### Python（requests）

```python
import requests, base64, json

url = "https://api.cxsee.com/v1/images/generations"
headers = {"Authorization": "Bearer <你的API令牌>", "Content-Type": "application/json"}
payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": "一只猫的插画，暖色调",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url",   # 或 "b64_json"
}

resp = requests.post(url, headers=headers, json=payload, timeout=180)
resp.raise_for_status()
data = resp.json()["data"]

# url 模式：直接得到链接
for item in data:
    print("图片链接:", item["url"])

# b64_json 模式：把 base64 写成文件
for i, item in enumerate(data):
    img_bytes = base64.b64decode(item["b64_json"])
    with open(f"grok_{i}.jpeg", "wb") as f:
        f.write(img_bytes)
```

### Node.js（axios）

```javascript
const axios = require("axios");

const res = await axios.post(
  "https://api.cxsee.com/v1/images/generations",
  {
    model: "grok-imagine-image-2.0",
    prompt: "一只柴犬戴着宇航员头盔",
    aspect_ratio: "16:9",
    resolution: "1k",
    n: 1,
    response_format: "url",
  },
  {
    headers: { Authorization: "Bearer <你的API令牌>", "Content-Type": "application/json" },
    timeout: 180000,
  }
);

console.log(res.data.data[0].url);
```

---

## 8. 常见错误码

| HTTP | 说明 | 处理 |
|---|---|---|
| 401 | 令牌缺失 / 无效 | 检查 `Authorization: Bearer` 头 |
| 400 | 参数错误（含计费规则不匹配） | 核对 `model/prompt/resolution/size/aspect_ratio` 与余额 |
| 402 / 余额不足 | 令牌预算或账户余额不足 | 充值或更换高余令牌 |
| 429 | 触发限流 / 额度阈值 | 稍后重试，控制并发 |
| 5xx | 上游或服务暂不可用 | 退避重试，仍失败请提交工单 |

---

*文档对应版本：grok-imagine-image-2.0（2026-09-07）*

上一篇：Flux 绘画（OpenAI 兼容）下一篇：X.AI 对话（OpenAI 兼容）