# 图片

> POST /v1/images 的生图、改图（含遮罩）、图生图与变体：参数、响应、流式、计费、限额与错误。

来源：https://www.scirouter.cn/docs/images · 更新于 2026-10-23

```http
POST https://api.scirouter.cn/v1/images/generations
POST https://api.scirouter.cn/v1/images/edits
POST https://api.scirouter.cn/v1/images/variations
```

接口格式与 OpenAI Images API 一致，OpenAI 官方 SDK 将 base URL 设为 `https://api.scirouter.cn/v1` 即可调用。

**只能调用生图模型**，即 [`GET /models`](https://www.scirouter.cn/docs/models) 中 `scirouter.kind` 为 `image` 的模型。`scirouter.image` 说明该模型支持的尺寸、质量档位、单次最多张数、是否支持改图与变体的生成方式。模型种类不符时的错误见[错误](#错误)。

## 生图

```bash
curl https://api.scirouter.cn/v1/images/generations \
  -H "Authorization: Bearer $SCIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "一张钙钛矿太阳能电池结构的示意图，扁平插画风格",
    "size": "1536x1024",
    "quality": "high",
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 --decode > out.png
```

Python：

```python
import base64, os
from openai import OpenAI

client = OpenAI(base_url="https://api.scirouter.cn/v1", api_key=os.environ["SCIROUTER_API_KEY"])
img = client.images.generate(
    model="YOUR_IMAGE_MODEL_ID",
    prompt="一张钙钛矿太阳能电池结构的示意图，扁平插画风格",
    size="1536x1024",
    quality="high",
)
open("out.png", "wb").write(base64.b64decode(img.data[0].b64_json))
```

Node：

```javascript
import OpenAI from 'openai'

const client = new OpenAI({ baseURL: 'https://api.scirouter.cn/v1', apiKey: process.env.SCIROUTER_API_KEY })
const img = await client.images.generate({ model: 'YOUR_IMAGE_MODEL_ID', prompt: '一张图形摘要', size: '1024x1024' })
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | 生图模型的 id，或平台为其配置的别名 |
| `prompt` | 是 | 画面描述。长度上限由模型决定，常见为 32,000 字符 |
| `n` | 否 | 单次生成的张数，缺省为 1，上限为模型的 `scirouter.image.max_outputs` |
| `size` | 否 | `宽x高`。须为模型 `sizes.presets` 中的值，或满足 `sizes.custom` 的规则（宽高均为 `multiple_of` 的倍数，长宽比、像素与边长在范围内）；模型接受 `auto` 时可写 `auto`。不写时使用模型的 `sizes.default` |
| `quality` | 否 | 模型 `qualities` 中的一档，不写时使用 `default_quality`；模型 `quality_auto` 为 true 时可写 `auto`。不接受 `standard` / `hd` 等旧值 |
| `background` | 否 | `auto` / `transparent` / `opaque`。透明背景须模型支持（`transparent`），且输出格式为 `png` 或 `webp` |
| `output_format` | 否 | 模型 `output_formats` 中的一种，缺省为 `png` |
| `output_compression` | 否 | 0–100，只对 `jpeg` / `webp` 生效 |
| `response_format` | 否 | `b64_json`（缺省）或 `url`，见[响应](#响应) |
| `stream` / `partial_images` | 否 | 见[流式响应](#流式响应) |
| `moderation` | 否 | 平台固定按 `auto` 发送，写 `low` 时改为 `auto` |
| `user` / `safety_identifier` / `style` | 否 | 接收但不转给上游（`style` 是 DALL·E 时代的退役参数）。其他无法识别的字段同样丢弃，记录在调用记录的参数中 |

尺寸不合规时返回 400 `validation_failed`，`param` 为 `size`，`details.reason` 指明不满足的规则（`size_multiple_of`、`size_ratio`、`size_max_edge` 等）。

## 改图与图生图

```bash
curl https://api.scirouter.cn/v1/images/edits \
  -H "Authorization: Bearer $SCIROUTER_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL_ID" \
  -F "image[]=@figure.png" \
  -F "image[]=@reference.jpg" \
  -F "mask=@mask.png" \
  -F "prompt=把背景换成浅灰色，保留主体" \
  -F "response_format=b64_json"
```

| 项 | 规则 |
|---|---|
| 请求格式 | `multipart/form-data` |
| 图片字段 | 一张图写 `image`，多张写 `image[]`（官方 SDK 的发送方式；`image[0]`、`image[1]` 也可识别）。第一张为待修改的图 |
| 图片张数 | 上限为模型的 `scirouter.image.edit.max_images`（不超过 16）。模型的 `edit` 为 null 时不支持改图 |
| 图片格式 | PNG、JPEG、WebP，按文件内容识别，不看扩展名 |
| 图片与请求体大小 | 见[限额](#限额) |
| `mask`（可选） | 带透明通道的 PNG，与第一张图同宽同高，透明区域为待修改区域。模型 `edit.mask` 为 false 时不接受 |
| 其他字段 | 与生图相同。`input_fidelity` 只在模型声明支持时转发，否则丢弃 |

- 遮罩是给模型的参考，模型不一定严格按遮罩的形状修改。
- 不带遮罩、带多张参考图时为图生图：按描述用这几张图生成新图。

## 变体

`/images/variations` 在 OpenAI 侧已退役（DALL·E 2 / 3 也已下线）。平台保留该接口（`multipart`，一张 `image`，可带 `n`、`size`、`response_format`），按模型的 `scirouter.image.variations` 处理：

| 取值 | 平台的处理 |
|---|---|
| `native` | 原样转给仍支持该接口的上游 |
| `via_edit` | 用该图调用改图接口，提示词为平台的一句固定文字（「生成这张图片的一个变体：保持主体、构图与风格，细节可以不同。」），按改图计费 |
| `none` | 400 `validation_failed`，`details.reason` 为 `variations_unsupported` |

## 响应

```json
{
  "created": 1760918400,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1536x1024",
  "usage": {
    "input_tokens": 24, "input_tokens_details": { "text_tokens": 24, "image_tokens": 0 },
    "output_tokens": 6208, "output_tokens_details": { "image_tokens": 6208, "text_tokens": 0 },
    "total_tokens": 6232
  },
  "scirouter": { "request_id": "req_…", "cost_quota": 186240, "…": "…" }
}
```

数值为示例。

| `response_format` | 返回内容 |
|---|---|
| `b64_json`（缺省） | 上游返回的原始字节，不重新压缩，保留透明背景；只在文件元数据中加入 AI 生成内容标识，见 [AI 生成内容标识](#ai-生成内容标识) |
| `url` | 图片存入平台的对象存储，`data[].url` 有效期为 1 小时（平台运行参数可调），对象 24 小时后删除。流式不支持 `url` |

- `size`、`output_format` 按实际生成的图片填写。
- `usage` 为本次计费所用的用量。上游未返回用量、平台按估算扣费时，`scirouter.estimated` 为 true。

## 流式响应

请求带 `"stream": true` 时返回 `text/event-stream`：

- 生成期间每隔几秒发送一行 `: ping` 心跳。
- 每张图生成后发送一个完成事件：生图为 `image_generation.completed`，改图与变体为 `image_edit.completed`。字段包括 `b64_json`、`size`、`quality`、`output_format`、`usage`；用量只在最后一个事件中给全，之前的事件为 0。全部图片发送后结束。
- `partial_images` 接收但不发送中间图。OpenAI 的官方说明中，中间图本就可能少于请求数量或没有，SDK 照常处理。
- 出错时发送一帧带 `error` 的数据，SDK 抛出异常。

高质量大图通常需要一到两分钟。非流式请求平台最多等待 270 秒，超过后会被前置的网络设施断开。**大尺寸、高质量的请求使用流式**，流式有心跳，不受该限制。

## 计费

按 token 计费，单价见[定价](https://www.scirouter.cn/pricing)或 `scirouter.pricing`：

| 计价维度 | 内容 |
|---|---|
| `input_tokens` | 文本输入 |
| `image_input_tokens` | 图像输入（改图、图生图的输入图） |
| `image_output_tokens` | 图像输出 |
| 两个缓存输入维度 | 直接调用图片接口时上游一般不返回 |

单次生成多张、带多张参考图，均体现在 token 数中。

- 平台按上游返回的用量扣费；上游未返回时，按模型的估算表与实际出图的尺寸扣费（`scirouter.estimated`）。
- 开始前按估算的上界预扣，结束后多退少补。失败、超时与审核拦截均不扣费。
- 少数模型按张计费（`scirouter.image.metering` 为 `per_image`，维度为 `image_count`），此时响应不含 `usage`。

## 限额

| 项目 | 上限 |
|---|---|
| 请求体 | 64 MB（413 `payload_too_large`） |
| 单张输入图 | 20 MB，边长 8192，像素 4,000 万 |
| 并发的图片请求 | 个人 4 个，团队 16 个，与站内绘图合计。超出时返回 429 `rate_limited`，`details.scope` 为 `images` |
| 非流式等待 | 270 秒 |

每分钟请求数照常按套餐计算；图片的 token 不计入每分钟 token 数的限频。

## 幂等

带 `Idempotency-Key` 时，同键重试的结果：

| 情况 | 结果 |
|---|---|
| 同键的请求仍在处理 | 409 |
| `url` 模式，已完成 | 直接返回该次的结果 |
| `b64_json` 与流式，已完成 | 结果不保存，返回 409 `idempotency_conflict`，`details.reason` 为 `result_not_replayable`。不会重复生成、重复扣费 |

`b64_json` 与流式模式下需要再次生成时，更换 `Idempotency-Key`。

判断是否为同一请求时按字段与图片内容比较，同一张图重新上传、`multipart` 的分隔符不同不影响判断。

## 错误

| 状态码 | code | 触发条件 | 说明 |
|---|---|---|---|
| 400 | `validation_failed` | 模型种类不符：对话模型调用图片接口，或生图模型调用对话接口 | `details.reason` 为 `model_kind_mismatch` |
| 400 | `validation_failed` | 尺寸、质量、张数、格式或遮罩不符合模型要求 | `param` 指明字段 |
| 400 | `validation_failed` | 模型不支持改图或变体 | `details.reason` 为 `edit_unsupported` / `variations_unsupported` |
| 400 | `moderation_blocked` | 上游审核未通过 | 平台错误码 `scirouter_code` 为 `CONTENT_FILTERED`（对话接口此处为 `content_filter`）。不扣费 |
| 502 | `upstream_error` | 上游返回了响应，但不是可用的图片 | `details.reason` 为 `bad_image_output`。不扣费 |
| 503 | `model_unavailable` | 模型有计价维度尚未定价 | `details.reason` 为 `model_offline` |

其他错误（认证、余额、限频、上游超时）与对话接口相同，见[错误码](https://www.scirouter.cn/docs/errors)。

## AI 生成内容标识

按《人工智能生成合成内容标识办法》，平台在每张图片的文件元数据中写入 AI 生成内容的隐式标识（`AIGC` 字段），不在画面上叠加可见角标。

- 调用方将图片发布或提供给公众时，须按规定自行添加显式标识。
- 平台按规定留存提供记录（调用方、时间与图片的哈希，不含图片与提示词）不少于六个月。
- 站内百宝箱「绘图」生成的图片直接带有「AI生成」角标。