GPT-Image-2.5-Flare 文生图 - 数字先锋API文档

# GPT-Image-2.5-Flare 图像生成 API 对接文档

> **用途**：第三方软件 / 自有应用对接「GPT-Image-2.5-Flare 图像生成」能力
> **平台**：数字先锋API（api.cxsee.com）
> **适用对象**：平台注册会员（需有可用令牌与余额）
> **协议**：OpenAI 兼容 `/v1/images/generations` 接口（同步返回，一张约 16~55 秒）

---

## 1. 快速开始

### 1.1 生成一张图片（同步返回图片 URL）

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "画一只猫",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'
```

```json
{
  "created": 1789150116,
  "background": "opaque",
  "data": [
    {
      "url": "https://.../0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 10,
    "input_tokens_details": { "image_tokens": 0, "text_tokens": 10 },
    "output_tokens": 229,
    "output_tokens_details": { "image_tokens": 229, "text_tokens": 0 },
    "total_tokens": 239
  }
}
```

![](/uploads/editor/20260912/img_6aa44eb5c082f1.35337212.png)

---

## 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 请求体参数（JSON）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | **`gpt-image-2.5-flare`** |
| `prompt` | string | ✅ | 画面描述。**传空会返回 400**（`prompt is required`） |
| `size` | string | 否 | **控制画面尺寸的唯一有效参数**。格式 `宽x高`，如 `"1024x1024"` / `"1536x1024"` / `"1024x1536"` / `"2048x2048"`；也支持 `"auto"`。**不传时默认 `1254x1254`** |
| `quality` | string | 否 | 生成品质：`"low"`（默认）/ `"medium"` / `"high"` / `"auto"`。⚠️ **不支持 `"hd"`**（那是 DALL·E 的写法，会报错） |
| `n` | integer | 否 | 生成张数，默认 1。**按张计费**（见第 5 节） |
| `response_format` | string | 否 | `"url"` 返回图片链接；`"b64_json"` 返回 base64 数据。⚠️ **不传时默认返回 `b64_json`**，需要链接请显式传 `"url"` |
| `background` | string | 否 | 背景处理（如 `"opaque"` / `"transparent"`），透传上游 |
| `output_format` | string | 否 | 输出格式，默认 `png` |
| `moderation` | string | 否 | 内容审核档位，透传上游 |
| `user` | string | 否 | 调用方自定义用户标识（透传，便于对账） |

#### ⚠️ 两个「看起来能用但其实无效」的参数

平台 **不支持** `aspect_ratio` 和 `resolution` 两个字段 —— 它们不在平台图片请求结构中，会作为未知字段**原样透传给上游**，而上游也不识别，**最终被静默忽略**，请求仍返回 200 但尺寸是默认的 `1254x1254`。

| 参数 | 结论 | 应改为 |
|---|---|---|
| `aspect_ratio`（如 `"16:9"`） | ❌ **无效**，不影响输出尺寸 | 用 `size` 指定具体像素 |
| `resolution`（如 `"1k"` / `"2k"`） | ❌ **无效**，不影响输出尺寸与计费 | 用 `size` 指定具体像素 |

**常用尺寸对照（实测全部可用）：**

| 想要的画面 | 推荐写法 |
|---|---|
| 正方形 | `"size": "1024x1024"` |
| 横版 / 宽屏 | `"size": "1536x1024"` |
| 竖版 / 手机壁纸 | `"size": "1024x1536"` |
| 大图 | `"size": "2048x2048"` |
| 交给模型决定 | `"size": "auto"` |

> `size` 为宽松透传：非标准尺寸（如 `"999x999"`）也不会报错，会交由上游处理；建议使用上表中的标准值以获得稳定效果。

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

不传 `response_format` 时的**默认行为**就是返回 base64，也可显式指定：

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "水墨风格的西湖",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }' > resp.json

cat resp.json | jq -r '.data[0].b64_json' | base64 -d > output.png
```

### 4.3 生成多张

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一只猫坐在窗台上，暖色阳光",
    "size": "1024x1024",
    "n": 2,
    "response_format": "url"
  }'
```

`data` 数组长度 = `n`，每项含独立的 `url`。

### 4.4 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `created` | int | 生成时间（Unix 秒） |
| `background` | string | 背景模式，如 `"opaque"` |
| `data[].url` | string | （`url` 模式）图片链接，**带签名、有效期 7 天** |
| `data[].b64_json` | string | （`b64_json` 模式）base64 编码图片数据 |
| `output_format` | string | 输出格式，如 `"png"` |
| `quality` | string | 本次生成实际使用的品质档 |
| `size` | string | 本次实际生成的像素尺寸 |
| `usage` | object | token 用量明细（**仅作统计展示，不参与计费**） |

**`usage` 明细：**

| 字段 | 说明 |
|---|---|
| `input_tokens` | 输入 token 数（文本提示词，通常 6~12） |
| `input_tokens_details.text_tokens` | 文本输入 token |
| `input_tokens_details.image_tokens` | 图片输入 token（文生图时为 0） |
| `output_tokens` | 输出 token 数（出图约 200~1800） |
| `output_tokens_details.image_tokens` | 图片输出 token |
| `total_tokens` | 合计 |

> ⚠️ 本模型为**按张固定价**计费，`usage` 里的 token 数字仅供观察，**不要用它估算费用**（见第 5 节）。

---

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

GPT-Image-2.5-Flare **按「张数」固定价计费**（`size_fixed` 逻辑，非按 token）：

| 模型 | 单价（USD / 张） |
|---|---|
| **`gpt-image-2.5-flare`** | **$0.16** |
| `gpt-image-2.5-flare-c` | $0.15 |
| `gpt-image-2.5-flare-2k` | $0.20 |
| `gpt-image-2.5-flare-4k` | $0.20 |

**本模型计价规则（实测确认）：**

- 一次请求 `n` 张 → 费用 = **$0.16 × n**
- 例：`n=2` → $0.32
- ⭐ **`size` 不影响价格**：`1024x1024`、`1536x1024`、`2048x2048` 均为 $0.16/张
- ⭐ **`quality` 不影响价格**：`low`、`medium`、`high` 均为 $0.16/张

> 即：直接传 `size: "2048x2048"` 或 `quality: "high"` 与默认档同价。

- 计费成功后可在控制台 →「用量日志」查看本次扣费明细（按模型 + 消费，日志中会标注「大小 xxx, 品质 xxx, 生成数量 x」）
- 平台金额以美元展示（`$1 = 500000 quota`，即 $0.16 = 80000 quota）

> 请确保令牌余额足够覆盖整批 `n` 张费用，否则提交会被拒。

---

## 6. 使用建议与限制

- **尺寸选择**：只用 `size`，不要用 `aspect_ratio` / `resolution`（后者被忽略）。
- **品质选择**：需要更精细的画面时用 `quality: "high"`；不要传 `"hd"`（会报 400）。
- **返回格式**：需要 HTTP 链接请**显式传** `response_format: "url"`；否则默认给 base64（体积大、需自行解码）。
- **出图耗时**：实测单张 **16~55 秒**（受尺寸与上游负载影响）。请把客户端超时设为 **≥ 120 秒**，并避免过早重试导致重复计费。
- **图片链接有效期**：`url` 模式返回的是**带签名的临时链接（7 天）**。如需长期使用，请自行转存到自己的 OSS / CDN。
- **并发建议**：单账号建议并发 ≤ 5，避免上游限流（`429`）。
- **内容安全**：请遵守平台内容合规条款，勿提交违规 / 版权敏感 prompt。
- **重试策略**：遇到 `429`、`5xx` 可做退避重试（建议间隔 5~10 秒）；`400` 类参数错误请先修正入参再重试（重试也不会成功，且可能持续失败计数）。

---

## 7. 各语言示例

### Python（requests）

```python
import requests, base64

url = "https://api.cxsee.com/v1/images/generations"
headers = {
    "Authorization": "Bearer <你的API令牌>",
    "Content-Type": "application/json",
}
payload = {
    "model": "gpt-image-2.5-flare",
    "prompt": "一只猫的插画，暖色调",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "response_format": "url",   # 需 base64 则填 "b64_json"
}

resp = requests.post(url, headers=headers, json=payload, timeout=180)
resp.raise_for_status()
result = resp.json()

print("实际尺寸:", result.get("size"))
print("实际品质:", result.get("quality"))

for i, item in enumerate(result["data"]):
    if "url" in item:
        print(f"图片{i}链接:", item["url"])
    else:
        with open(f"flare_{i}.png", "wb") as f:
            f.write(base64.b64decode(item["b64_json"]))
```

### Node.js（axios）

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

const res = await axios.post(
  "https://api.cxsee.com/v1/images/generations",
  {
    model: "gpt-image-2.5-flare",
    prompt: "一只柴犬戴着宇航员头盔",
    size: "1536x1024",
    quality: "high",
    n: 1,
    response_format: "url",
  },
  {
    headers: {
      Authorization: "Bearer <你的API令牌>",
      "Content-Type": "application/json",
    },
    timeout: 180000,
  }
);

console.log("尺寸:", res.data.size);
res.data.data.forEach((item, i) => console.log(`图片${i}:`, item.url));
```

---

## 8. 常见错误码

| HTTP | 报错信息 / 说明 | 处理 |
|---|---|---|
| 401 | 令牌缺失 / 无效 | 检查 `Authorization: Bearer` 头 |
| 400 | `prompt is required` | `prompt` 不能为空 |
| 400 | `quality must be one of: auto, low, medium, high, xhigh, max` | 改用 `low` / `medium` / `high` / `auto`，**不要用 `hd`** |
| 400 | `Invalid value: '<x>'. Supported values are: 'low', 'medium', 'high', and 'auto'` | 同上，`quality` 取值超出上游支持范围 |
| 402 | 余额不足 | 充值或更换高余令牌 |
| 429 | 触发限流 | 降低并发，稍后重试 |
| 500 / 503 | `The model service is temporarily unavailable. Please try again later.` | **上游临时不可用**（非参数问题），退避 5~10 秒后重试；若持续出现请提交工单 |

> `400` 与 `404` 类错误不会扣费；`503` 失败同样不扣费（失败自动释放预扣额度）。

---

## 9. 附：相关模型

同系列模型（同一接口，仅 `model` 名不同）：

| 模型名 | 单价（$/张） | 说明 |
|---|---|---|
| `gpt-image-2.5-flare` | 0.16 | 本文档主模型 |
| `gpt-image-2.5-flare-c` | 0.15 | 价格更优通道 |
| `gpt-image-2.5-flare-2k` | 0.20 | 2K 档 |
| `gpt-image-2.5-flare-4k` | 0.20 | 4K 档 |
| `gpt-image-2.5-sunburst` | 0.16 | 风格变体 |
| `gpt-image-2.5-sunburst-4k` | 0.20 | 风格变体 4K |

> 💡 由于 `gpt-image-2.5-flare` 传 `size` 即可输出大尺寸且单价固定 $0.16，一般**无需**切到 `-2k` / `-4k` 变体。

---

*文档对应版本：gpt-image-2.5-flare（2026-09-12 实测校准）*

上一篇：OpenAI 图像生成（绘画）下一篇：GPT-Image-2.5-Flare 图像编辑