# ZPIKA 图片接口 AI 接入规范

本文档供 AI 编程助手、自动化代理和第三方客户端直接读取。请严格使用本文定义的 ZPIKA 接口格式，不要根据其它 Gemini 或 GPT Image 服务商的字段自行猜测。

## 1. 固定接入信息

- Base URL：`https://vip.zpika.com`
- 文生图：`POST /v1/images/generations`
- 参考图 / 编辑：`POST /v1/images/edits`
- 认证：`Authorization: Bearer YOUR_API_KEY`
- 密钥创建：<https://vip.zpika.com/keys>
- 使用日志：<https://vip.zpika.com/usage-logs>
- Content-Type：JSON 请求使用 `application/json`

新图片接入默认使用 OpenAI Images 格式。GPT Image 和采用 OpenAI Images 格式的 Gemini 模型都调用 `/v1/images/generations` 或 `/v1/images/edits`；参考图当前只接受服务端可直接读取的公网 HTTPS URL。没有图床时可使用本站无限画布上传素材，由画布生成并提交素材 URL。

只有调用方必须直接提交 Base64 参考图时，才使用 Gemini 原生 `/v1beta/models/{model}:generateContent`。原生格式只使用不带 `preview` 的 `gemini-3.1-flash-image` 和 `gemini-3.0-pro-image`，参考图放在 `inlineData.data`。不要把这两个模型名或 `inlineData` 混入 OpenAI Images 请求。

图片接口同时支持客户端同步和异步两种调用方式。省略 `async` 或传 `"async": false` 时，网关会在当前请求内轮询上游任务，完成后返回普通 OpenAI Images 响应；传 `"async": true` 时，网关立即返回任务对象，客户端必须保存任务 ID 并轮询查询。两种方式最终使用同一套计费、任务日志和制品逻辑。

注意：当前图片上游本身始终使用异步任务。这里的 `async` 只控制 ZPIKA 对客户端的响应方式，不会原样决定上游协议。Gemini 原生 Base64 路径是独立渠道，不使用本文的 OpenAI Images 异步任务格式。

### 协议选择

| 场景 | 首选协议 | 模型名 | 参考图输入 |
| --- | --- | --- | --- |
| 文生图、URL 参考图、画布上传素材 | OpenAI Images（主推） | GPT Image，或带 `preview` 的 Gemini 模型 | 公网 HTTPS URL |
| 必须直接提交 Base64 参考图 | Gemini 原生（例外） | `gemini-3.1-flash-image` / `gemini-3.0-pro-image` | `inlineData.data` Base64 |

不要仅根据模型家族判断协议：带 `preview` 与不带 `preview` 是本站不同渠道的公共名，端点和请求体也不同。

## 2. 模型与能力

### Gemini Preview

| 模型 | 清晰度 | 参考图 | 说明 |
| --- | --- | ---: | --- |
| `gemini-3.1-flash-image-preview` | `quality: 1k / 2k / 4k` | 最多 9 张 | 速度和性价比优先 |
| `gemini-3-pro-image-preview` | `quality: 1k / 2k / 4k` | 最多 9 张 | 复杂构图、多图融合和质量优先 |

两条 Gemini Preview 模型的公开档案都列出了最多 1 张 `mask`。不要把 `low`、`medium`、`high`、`xhigh`、`max` 用于 Gemini。

### GPT Image 网页档与全站两个超分模型

| 模型 | 输出定位 | 参考图 | 特性 |
| --- | --- | ---: | --- |
| `gpt-image-2` | 最高约 1.5K | 最多 9 张 | 透明背景；本站已验证蒙版编辑 |
| `gpt-image-2.5` | 最高约 1.5K | 最多 9 张 | 透明背景 |
| `gpt-image-2.5-flare` | 最高约 1.5K | 最多 9 张 | Flare；透明背景 |
| `gpt-image-2.5-sunburst` | 最高约 1.5K | 最多 9 张 | Sunburst；透明背景 |
| `gpt-image-2.6` | web 出图，最高约 1.5K | 最多 9 张 | 透明背景；唯一支持 GIF / SVG 的 2.6 公共名 |
| `gpt-image-2.6-flare` | 无 K 超分静图 | 最多 9 张 | Flare：快速迭代、商品图与海报版式；透明背景 |
| `gpt-image-2.6-sunburst` | 无 K 超分静图 | 最多 9 张 | Sunburst：细节与精确编辑；透明背景 |

全站只有 `gpt-image-2.6-flare` 和 `gpt-image-2.6-sunburst` 属于超分模型。`gpt-image-2.6` 是 web 出图，不是超分。这三个无 K 模型都不要传 `quality`；两个超分模型按自己的尺寸出图，不套 1K / 2K / 4K 像素上限。只有模型名带 `-1k`、`-2k`、`-4k` 的档位才使用质量参数。

### 无限画布的折叠模型路由

无限画布不把所有完整模型 ID 平铺在一个下拉框中，而是按“基础系列 → 档位 → 质量”选择。当前 Key 没有返回的档位不会显示。

| 画布基础系列 | 画布档位 | 实际提交的 `model` |
| --- | --- | --- |
| `gpt-image-2.6` | Web（最高约 1.5K） | `gpt-image-2.6` |
| `gpt-image-2.6-flare` | 超分 | `gpt-image-2.6-flare` |
| `gpt-image-2.6-flare` | 1K / 2K / 4K | `gpt-image-2.6-flare-1k` / `-2k` / `-4k` |
| `gpt-image-2.6-sunburst` | 超分 | `gpt-image-2.6-sunburst` |
| `gpt-image-2.6-sunburst` | 1K / 2K / 4K | `gpt-image-2.6-sunburst-1k` / `-2k` / `-4k` |

这只是画布交互，不是 API 新增了基础别名或 `tier` 参数。第三方程序直接调用 API 时，必须把最终完整模型名写入 `model`。

### GPT Image 2 原生固定档

| 模型 | 像素档 | 参考图 | 定价 |
| --- | --- | ---: | --- |
| `gpt-image-2-1k` | 1K | 最多 9 张 | 固定价，不分 std / xhigh |
| `gpt-image-2-2k` | 2K | 最多 9 张 | 固定价，不分 std / xhigh |
| `gpt-image-2-4k` | 4K | 最多 9 张 | 固定价，不分 std / xhigh |

公开模型档案接受 `low`、`medium`、`high`、`xhigh`、`max`，但本站对这三条模型按模型名固定计价。

### GPT Image 2.5 / 2.6 原生 Flare、Sunburst

完整模型名：

- `gpt-image-2.5-flare-1k`
- `gpt-image-2.5-flare-2k`
- `gpt-image-2.5-flare-4k`
- `gpt-image-2.5-sunburst-1k`
- `gpt-image-2.5-sunburst-2k`
- `gpt-image-2.5-sunburst-4k`
- `gpt-image-2.6-flare-1k`
- `gpt-image-2.6-flare-2k`
- `gpt-image-2.6-flare-4k`
- `gpt-image-2.6-sunburst-1k`
- `gpt-image-2.6-sunburst-2k`
- `gpt-image-2.6-sunburst-4k`

规则：

- 模型名后缀决定 1K / 2K / 4K 像素档。
- 最多 16 张参考图。
- `quality: low / medium / high` 统一按 std 价。
- GPT Image 2.5 原生型号支持 `quality: xhigh / max`，统一按 xhigh 价；客户端应提供 `low`、`medium`、`high`、`xhigh`、`max` 五个质量选项。
- GPT Image 2.6 原生型号同样支持 `quality: low / medium / high / xhigh / max`；`low / medium / high` 按 std 价，`xhigh / max` 按 xhigh 价。
- Flare 更适合快速迭代、日常出图、商品图、海报和批量试稿。
- Sunburst 更适合细节与精确编辑、参考图局部修改和多轮迭代。

## 3. 文生图

本站文档默认推荐异步调用。创建成功后保存任务 ID，再查询原任务：

```bash
curl -X POST 'https://vip.zpika.com/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2.5-flare-2k",
    "prompt": "白色背景上的钴蓝色陶瓷花瓶，商品摄影，柔和棚拍光",
    "size": "1:1",
    "quality": "high",
    "output_format": "png",
    "n": 1,
    "async": true
  }'
```

创建成功后先保存 `id`：

```json
{
  "created_at": 1794284887,
  "id": "task_...",
  "model": "gpt-image-2.5-flare-2k",
  "object": "image.generation",
  "progress": "20%",
  "status": "queued"
}
```

使用原任务 ID 查询，不要再次创建：

```bash
curl --fail-with-body --silent --show-error \
  'https://vip.zpika.com/v1/images/generations/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

建议每 5–10 秒查询一次；`queued`、`in_progress` 继续等待，`completed` 读取 `data`，`failed` 读取 `error` 并停止轮询。请求超时或客户端断线后不要立即重提，先继续查询已保存的任务 ID。省略 `async` 或显式传 `false` 时仍兼容同步等待，但不再作为本文默认示例。

Gemini 示例：

```json
{
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "雨夜霓虹街道上的未来感跑车，电影级灯光，无文字",
  "size": "16:9",
  "quality": "2k",
  "n": 1,
  "async": true
}
```

网页档示例：

```json
{
  "model": "gpt-image-2.6",
  "prompt": "雨夜霓虹街道上的未来感跑车，电影级灯光，无文字",
  "size": "16:9",
  "n": 1,
  "async": true
}
```

网页档不要增加 `quality`。

无 K 超分静图示例：

```json
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "精确保留产品轮廓与标签，只改善材质细节和棚拍光线",
  "images": ["https://example.com/reference.png"],
  "size": "4:3",
  "background": "transparent",
  "output_format": "png",
  "n": 1,
  "async": true
}
```

这个请求不要增加 `quality`。透明背景必须使用 PNG 或 WebP。

## 4. 响应与下载

- 客户端默认传 `async: true`，保存任务 ID并轮询到终态，避免依赖长时间 HTTP 连接。
- 完成时从 `data[].url` 读取结果。URL 可能是临时地址，应尽快下载并转存到自己的存储。
- 异步请求返回任务对象；终态查询返回 `data[].url` 或 `data[].b64_json`。同步请求直接返回终态图片响应。
- 异步任务的图片地址通常是 ZPIKA 制品地址，例如 `/v1/tasks/{task_id}/artifacts/image-1/content`，也可能经过配置的媒体域名重定向到 `/v1/media?...`。这是有签名和有效期的能力 URL，不保证以 `.png`、`.jpg` 等扩展名结尾。
- 下载图片时跟随 HTTP 重定向，并以响应的 `Content-Type` 判断格式；不要根据 URL 后缀判断图片类型。当前 R2 制品默认保留 24 小时，客户端应在拿到结果后尽快下载或转存。
- 需要刷新制品地址时，可使用 `GET /v1/tasks/{task_id}/artifacts`，从返回的 `artifacts[].content_url` 读取新的地址；该接口只列出已完成且仍可取回的制品。
- 请求超时或连接中断时，先继续查询已保存的任务 ID并检查使用日志，再决定是否重新提交，避免重复扣费。
- 若响应返回 `b64_json`，按标准 Base64 图片内容解码，不要把它当作 URL。它是输出字段，不代表 OpenAI Images 支持 Base64 参考图输入。

## 5. 参考图与编辑

OpenAI Images 静图参考图使用 `images` 数组，元素只能是服务端无需登录即可读取的公网 HTTPS 图片直链。不要传 Base64、data URL、浏览器 `blob:` URL、需要登录的网页或网盘分享页。没有图床时先通过本站无限画布上传。2.6 web 与两个超分模型最多 9 张；带 K 的 2.6 Flare / Sunburst 最多 16 张。编辑任务同样默认使用异步模式。

```bash
curl -X POST 'https://vip.zpika.com/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2.6-sunburst-2k",
    "prompt": "把花瓶改成钴蓝色陶瓷，保留形状、干花和背景",
    "images": ["https://example.com/reference.png"],
    "size": "1:1",
    "quality": "high",
    "output_format": "png",
    "n": 1,
    "async": true
  }'
```

创建响应中的 `object` 为 `image.edit`。保存返回的 `id`，然后通过编辑查询路径轮询：

```bash
curl --fail-with-body --silent --show-error \
  'https://vip.zpika.com/v1/images/edits/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

完成响应示例：

```json
{
  "id": "task_...",
  "object": "image.edit",
  "model": "gpt-image-2.6-sunburst-2k",
  "status": "completed",
  "progress": "100%",
  "data": [
    {"url": "https://vip.zpika.com/v1/tasks/task_.../artifacts/image-1/content?access=..."}
  ]
}
```

不要把正式请求改写为 `image`、`input_reference` 或 `aspect_ratio`。

### Base64 参考图例外

Base64 参考图不能提交到 OpenAI Images 路径。必须改用 Gemini 原生 `generateContent`，模型名也必须切换为不带 `preview` 的公共名：

- `gemini-3.1-flash-image`
- `gemini-3.0-pro-image`

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "保留主体结构，改成夜景霓虹灯光"},
      {"inlineData": {"mimeType": "image/png", "data": "BASE64_IMAGE_DATA"}}
    ]
  }]
}
```

请求路径为 `/v1beta/models/{model}:generateContent`。这是单独的 Gemini 原生协议，不使用 OpenAI Images 的 `images`、`async`、任务查询路径或带 `preview` 的模型名。除非确实需要 Base64 输入，否则仍优先使用 OpenAI Images + URL 参考图。

## 6. 蒙版编辑

- Gemini 两条 Preview 模型档案列出最多 1 张 `mask`。
- 本站已验证 `gpt-image-2` 支持 OpenAI Images 编辑格式的原图 + PNG 蒙版。
- 其他模型未明确列出时，不要假设支持蒙版。
- 蒙版必须与原图像素尺寸一致并带 Alpha 通道。
- 透明区域表示允许修改，不透明区域表示希望保留。
- 蒙版是语义约束，不是像素级锁定。

```bash
curl -X POST 'https://vip.zpika.com/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "只把蒙版区域内的车身改成绿色金属漆",
    "images": ["https://example.com/source.png"],
    "mask": "https://example.com/mask.png",
    "n": 1,
    "async": true
  }'
```

## 7. 透明背景

GPT Image 2.6 的 web 名、无 K 超分和带 K 档支持 `background: auto / opaque / transparent`。无 K 的三条模型是：

- `gpt-image-2.6`
- `gpt-image-2.6-flare`
- `gpt-image-2.6-sunburst`

```json
{
  "background": "transparent",
  "output_format": "png",
  "response_format": "url",
  "async": true
}
```

静图 `output_format` 支持 `png`、`jpeg`、`webp`。透明结果必须使用 PNG 或 WebP，JPEG 没有透明通道。

## 8. 尺寸与比例

带 K 型号的像素档由模型名后缀锁定。`gpt-image-2.6-flare-2k` 始终是 2K 档，不能通过 `quality` 或 `size` 改成 1K / 4K。无限画布只让用户选择比例，不提供像素分辨率输入。

直接调用 API 时，`size` 可以传比例；上游也接受符合该档像素预算的 `宽x高`，但这不会改变模型档位。常用比例：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`5:4`、`4:5`、`21:9`。不要另传 `aspect_ratio`。

GPT 原生档像素预算：

| 档位 | 方图 | 像素上限 |
| --- | --- | ---: |
| 1K | 1024×1024 | 1,048,576 |
| 2K | 2048×2048 | 4,194,304 |
| 4K | 2880×2880 | 8,294,400 |

自定义宽高按 16 对齐；最长边不超过 3840；宽高比不超过 3:1；像素不少于 655,360。4K 方图不是 4096×4096。

这张像素预算表只约束带 K 的公共名。`gpt-image-2.6` web 出图及无 K Flare / Sunburst 超分不按 1K / 2K / 4K 像素上限理解。Gemini 的 `quality` 选择 1K / 2K / 4K，`size` 控制画幅。

## 9. GPT Image 2.6 GIF / SVG

GIF 和 SVG 只使用 `gpt-image-2.6`。不能改用 Flare、Sunburst 或带 K 型号，仍使用图片接口，不要调用 `/v1/videos`。

```json
{
  "model": "gpt-image-2.6",
  "prompt": "固定镜头下红色立方体缓慢旋转，无缝循环，无文字",
  "output_format": "gif",
  "response_format": "url",
  "async": true
}
```

- GIF 不使用蒙版。
- `frame_count` 使用 2–16，默认 9。上游章节允许更大的 `frame_duration_ms`，但当前模型目录的兼容上限是 2000；本站接入请使用 20–2000 毫秒，默认 200。
- GIF 模式下 `size` 和 `quality` 不生效，成片尺寸由模型决定。
- 图生 GIF 使用 `/v1/images/edits`，参考图写成 `images: [{"image_url":"https://..."}]`，当前只接受 HTTPS URL，不接受 data URL。
- 本文价格表是静态图片报价；GIF 实际可用模型与扣费以站内说明和使用日志为准。

SVG 示例：

```json
{
  "model": "gpt-image-2.6",
  "prompt": "白色画布中央的青绿色几何标志，使用清晰的矢量路径，无文字",
  "n": 1,
  "output_format": "svg",
  "response_format": "url",
  "async": true
}
```

SVG 不要传 GIF 的帧参数。有参考图时同样调用 `/v1/images/edits` 并使用 `images[].image_url`。

## 10. 客户价格

充值换算：支付 ¥36 获得 $300 站内余额，即每 $1 余额对应 ¥0.12。

### Gemini

| 模型 | 1K | 2K | 4K |
| --- | ---: | ---: | ---: |
| `gemini-3-pro-image-preview` | $1.050 / ¥0.126 | $1.350 / ¥0.162 | $1.650 / ¥0.198 |
| `gemini-3.1-flash-image-preview` | $0.900 / ¥0.108 | $1.200 / ¥0.144 | $1.500 / ¥0.180 |

### GPT 网页档与 2.6 无 K 超分

| 模型 | 单张静态图 |
| --- | ---: |
| `gpt-image-2` | $0.188 / 约 ¥0.023 |
| `gpt-image-2.5` | $0.188 / 约 ¥0.023 |
| `gpt-image-2.5-flare` | $0.313 / 约 ¥0.038 |
| `gpt-image-2.5-sunburst` | $0.313 / 约 ¥0.038 |
| `gpt-image-2.6` | $0.188 / 约 ¥0.023 |
| `gpt-image-2.6-flare` | 以站内实时价格为准 |
| `gpt-image-2.6-sunburst` | 以站内实时价格为准 |

### GPT Image 2 原生固定档

| 模型 | 单张静态图 |
| --- | ---: |
| `gpt-image-2-1k` | $0.750 / ¥0.090 |
| `gpt-image-2-2k` | $1.050 / ¥0.126 |
| `gpt-image-2-4k` | $2.700 / ¥0.324 |

### GPT 2.5 原生 Flare、Sunburst

| 系列与档位 | std：low / medium / high | xhigh：xhigh / max |
| --- | ---: | ---: |
| Flare 1K | $2.400 / ¥0.288 | $4.800 / ¥0.576 |
| Flare 2K | $2.700 / ¥0.324 | $5.400 / ¥0.648 |
| Flare 4K | $3.000 / ¥0.360 | $6.000 / ¥0.720 |
| Sunburst 1K | $2.700 / ¥0.324 | $5.400 / ¥0.648 |
| Sunburst 2K | $3.000 / ¥0.360 | $6.000 / ¥0.720 |
| Sunburst 4K | $3.300 / ¥0.396 | $6.600 / ¥0.792 |

### GPT 2.6 原生 Flare、Sunburst

GPT Image 2.6 带 K 型号支持五个质量值；`low / medium / high` 按 std 结算，`xhigh / max` 按 xhigh 结算。

| 系列与档位 | std：low / medium / high | xhigh：xhigh / max |
| --- | ---: | ---: |
| Flare 1K | $2.400 / ¥0.288 | $4.800 / ¥0.576 |
| Flare 2K | $2.700 / ¥0.324 | $5.400 / ¥0.648 |
| Flare 4K | $3.000 / ¥0.360 | $6.000 / ¥0.720 |
| Sunburst 1K | $2.700 / ¥0.324 | $5.400 / ¥0.648 |
| Sunburst 2K | $3.000 / ¥0.360 | $6.000 / ¥0.720 |
| Sunburst 4K | $3.300 / ¥0.396 | $6.600 / ¥0.792 |

## 11. 客户端实现要求

- 不得把 API Key 写入公开前端代码、URL、仓库或日志。
- 未传 `async` 时等待同步结果；传 `async: true` 时保存任务 ID并轮询 `/v1/images/generations/{task_id}` 或 `/v1/images/edits/{task_id}`。
- 轮询客户端必须支持 `queued`、`in_progress`、`completed`、`failed`，并在页面刷新后恢复原任务轮询。
- 将客户端超时设置到足以覆盖高分辨率图片生成的范围。
- 超时或连接中断后先检查使用日志，避免盲目重复创建。
- 收到 `data[].url` 后尽快下载并转存，不要依赖上游临时 URL 长期有效。
- 请求前按模型校验 `quality`、参考图数量、尺寸和输出格式。
- OpenAI Images 的输入参考图只接受公网 HTTPS URL；Base64 输入必须切换到 Gemini 原生协议和不带 `preview` 的两个模型名。
- 所有本文模型单次请求固定使用 `n: 1`；需要多张结果时，由客户端分别提交多个独立请求。
- `gpt-image-2.6`、`gpt-image-2.6-flare`、`gpt-image-2.6-sunburst` 不得传 `quality`。
- Gemini 的 `quality` 只能是 `1k`、`2k`、`4k`。
- GPT 2.5 原生档显示 `low/medium/high/xhigh/max`，并按 std / xhigh 规则显示预估价格。
- GPT 2.6 带 K 档显示并支持 `low/medium/high/xhigh/max`，并按 std / xhigh 规则显示预估价格。
- 透明背景不得使用 JPEG。
- 内容审核拒绝后应修改提示词或素材，不要原样重复提交。
- 请求失败后的本站余额变化以使用日志为准。

## 12. 画布 / 客户端实现建议

- 图片节点默认使用 `async: true` 以支持稳定的断线恢复；确实只需要一次性结果时，仍可省略该字段使用同步兼容模式，并把 HTTP 超时设置到足够长。
- 异步完成后优先读取 `data[].url`，并将其当作不透明 URL；不要拼接文件名、替换域名或自行移除查询参数。
- 若客户端需要下载二进制，可直接请求返回的 URL；也可以保留任务 ID，使用任务制品接口重新取得同一制品。制品访问失败时先重取任务结果或制品列表，不要重新生成。
- 图片 OpenAI 格式和 Gemini 原生格式是两条独立路径。默认选择 OpenAI Images + URL 参考图；只有需要 Base64 参考图时才选 Gemini 原生分组。画布应根据所选分组使用对应端点，不能混用模型名、字段或任务查询路径。
