图像生成与编辑

无界模型云提供与 OpenAI Images API 兼容的图像能力：纯文本生成图像（文生图）、单图编辑（图生图）、最多 16 张参考图的多图融合，以及通过 mask 做局部重绘（inpainting）。当前主力模型为 gpt-image-2，在中文提示词、版式控制与图文一致性上表现稳定，适合电商主图、海报、插画、产品图融合等场景。

私有化部署 API 完全一致，仅需替换 Base 域名 → 企业私有化部署。

概览

• 文生图：POST https://api.tos.run/v1/images/generations，application/json。
• 图生图 / 多图编辑：POST https://api.tos.run/v1/images/edits，multipart/form-data。
• model 传 gpt-image-2（具体可用模型以模型列表和控制台展示为准）。
• 多图编辑是核心能力：用重复的 image[] 字段上传多张参考图，在提示词里用「图1 / 图2 / 图3」按上传顺序引用。

接口与 OpenAI Images API 兼容，已有 OpenAI 图像客户端只需切换 Base、Key 和 model 即可接入。需要注意的是，本网关只透传它真正支持的参数，其余 OpenAI 参数会被忽略——具体见下方「参数」与「OpenAI 兼容性」两节。

鉴权与 Base

• API 数据面 Base：https://api.tos.run/v1（所有 /v1/* 调用都打到 api.tos.run）。
• 控制台 https://ai.tos.run 仅用于浏览器管理，不要作为 curl / SDK 的 API Base。
• 鉴权头：Authorization: Bearer $TOS_API_KEY，Key 以 gk_ 开头。

API Key 在控制台创建，调用时通过 Authorization 头传入。生产环境请把 Key 放在服务端，不要暴露到浏览器。详见 鉴权。

文生图

向 /v1/images/generations 发送 JSON 请求，传入 model、prompt，以及可选的 size、quality。文生图只生成单张图片，输出格式固定为上游默认的 PNG。

curl "https://api.tos.run/v1/images/generations" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "灰色桌面上的白色陶瓷马克杯，柔和自然光，电商主图风格",
    "size": "1024x1024",
    "quality": "auto"
  }'

import os
import base64
import requests

resp = requests.post(
    "https://api.tos.run/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['TOS_API_KEY']}"},
    json={
        "model": "gpt-image-2",
        "prompt": "灰色桌面上的白色陶瓷马克杯，柔和自然光，电商主图风格",
        "size": "1024x1024",
        "quality": "auto",
    },
    timeout=600,
)
resp.raise_for_status()
data = resp.json()
b64 = data["data"][0]["b64_json"]
with open("out.png", "wb") as f:
    f.write(base64.b64decode(b64))

import fs from "node:fs";

const resp = await fetch("https://api.tos.run/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "灰色桌面上的白色陶瓷马克杯，柔和自然光，电商主图风格",
    size: "1024x1024",
    quality: "auto",
  }),
});
const data = await resp.json();
fs.writeFileSync("out.png", Buffer.from(data.data[0].b64_json, "base64"));

图生图与多图编辑

向 /v1/images/edits 发送 multipart/form-data 请求。

单图编辑

只传一个 image 字段即可：

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product.png" \
  -F "prompt=把背景换成纯白电商主图背景，保留产品细节" \
  -F "size=1024x1024"

多图编辑（核心能力）

多张参考图用重复的 image[] 字段上传（OpenAI 数组式），最多 16 张，每张为 PNG / JPEG / WebP。上传顺序即引用顺序，在提示词里用「图1 / 图2 / 图3」指代对应的图片。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@bag.png" \
  -F "image[]=@scarf.png" \
  -F "image[]=@model.png" \
  -F "prompt=让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格" \
  -F "size=1024x1536"

import os
import base64
import requests

files = [
    ("image[]", ("bag.png", open("bag.png", "rb"), "image/png")),
    ("image[]", ("scarf.png", open("scarf.png", "rb"), "image/png")),
    ("image[]", ("model.png", open("model.png", "rb"), "image/png")),
]
resp = requests.post(
    "https://api.tos.run/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['TOS_API_KEY']}"},
    data={
        "model": "gpt-image-2",
        "prompt": "让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格",
        "size": "1024x1536",
    },
    files=files,
    timeout=600,
)
resp.raise_for_status()
img = resp.json()["data"][0]["b64_json"]
open("out.png", "wb").write(base64.b64decode(img))

import fs from "node:fs";

const form = new FormData();
form.set("model", "gpt-image-2");
form.set("prompt", "让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格");
form.set("size", "1024x1536");
for (const name of ["bag.png", "scarf.png", "model.png"]) {
  form.append("image[]", new Blob([fs.readFileSync(name)]), name);
}

const resp = await fetch("https://api.tos.run/v1/images/edits", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.TOS_API_KEY}` },
  body: form,
});
const data = await resp.json();
fs.writeFileSync("out.png", Buffer.from(data.data[0].b64_json, "base64"));

局部编辑（mask）

通过 mask 字段做局部重绘（inpainting）：只重绘 mask 的透明区域，保留不透明区域。mask 仅在 edits 接口的 multipart/form-data 下生效，网关会原样透传给上游（不做有损压缩，alpha 通道完整保留）。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@room.png" \
  -F "mask=@room-mask.png" \
  -F "prompt=把遮罩区域替换为一扇落地窗" \
  -F "size=1024x1024"

• mask 是一张带 alpha 通道的 PNG：透明区 = 要重绘的区域，不透明区 = 保留原样。
• mask 作用于第一张参考图（即第一个 image / image[]）。
• 只支持 multipart（不走 JSON body）；默认路径与策略路由 / 故障转移的编辑路径都生效。

输出格式与张数

• output_format（默认 png，可选 png / jpeg / webp）仅在 edits 接口生效，用于指定返回图片的编码格式。
• n（生成张数）仅在 edits 接口、且 n > 1 时下发；不传或为 1 时返回单张。文生图不支持 n，始终返回单张。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product.png" \
  -F "prompt=把背景换成纯白电商主图背景，保留产品细节" \
  -F "size=1024x1024" \
  -F "output_format=webp"

输入图压缩（edits 专属）

针对重型多图融合编辑，可通过请求头 x-input-image-compress: true 开启输入参考图的有损压缩，显著降低上传到上游、落盘的字节数，画质几乎无可见损失。仅对单张超过 200KB 的参考图生效，小图原样透传；若重编码后反而更大则保留原图。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "x-input-image-compress: true" \
  -F "model=gpt-image-2" \
  -F "image[]=@bag.png" \
  -F "image[]=@scarf.png" \
  -F "image[]=@model.png" \
  -F "prompt=让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格" \
  -F "size=1024x1536"

参数

下表列出本网关实际透传 / 生效的参数。未列出的 OpenAI 参数会被忽略，详见下方「OpenAI 兼容性」一节。

尺寸说明

size 既可以传一个尺寸档位（1K / 2K / 4K）配合文生图的 aspectRatio，也可以直接传显式的 宽x高。任何值都会被对齐（snap）到 gpt-image-2 支持的最接近像素尺寸。常用预设：

• 1024x1024、1536x1024、1024x1536
• 2048x2048
• 3840x2160、2160x3840

也支持自定义尺寸，建议满足：最长边 ≤ 3840、宽高均为 16 的倍数。竖版 3:4 常用 1728x2304。

OpenAI 兼容性

本接口与 OpenAI Images API 兼容，从 OpenAI 迁移时注意以下参数本网关暂未透传 / 暂不支持，设置后会被静默忽略：

• output_compression：压缩输出图——本网关不支持。如需压缩，可用 edits 的 x-input-image-compress 压缩输入参考图（用途不同，见上文）。
• background（opaque / transparent / auto）：不支持，gpt-image-2 默认输出不透明背景。
• output_format：文生图接口不支持（始终返回上游默认的 PNG），仅在 edits 生效。
• n：文生图接口不支持（始终单张），仅 edits 且 n > 1 时生效。
• 面向调用方的 stream / partial_images：不支持，调用方始终收到一次性的完整 JSON 响应（详见下方「响应」）。

响应

响应始终是一次性的完整 JSON，没有面向调用方的流式（网关与上游之间可能内部走流式以规避 Cloudflare 524 超时，但这对调用方透明，你只会拿到完整 JSON body）。

data[] 中的每张图片以 b64_json（纯 base64）或 url（serve URL）返回；usage 给出用量信息。

{
  "created": 1717488000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 256,
    "output_tokens": 1568,
    "total_tokens": 1824,
    "generated_images": 1
  }
}

• b64_json 为纯 base64 字符串，落盘或在前端展示前需自行拼接 data:image/png;base64, 前缀。
• url 为带时效的 serve 链接，请尽快转存到自有存储。
• usage 包含 input_tokens（上游上报时透出）、output_tokens、total_tokens 与 generated_images。

价格

按图片规格与画质档位（低 / 中 / 高）整张计费，1K 与 2K 同价，4K 价格更高。不传 quality（即 auto，由模型自动选择画质）时按对应规格的「高」档（基准价）计费。实际价格以控制台展示为准，组织专属价格优先。

耗时与错误处理

图像生成与编辑耗时受质量和分辨率影响较大，请把客户端超时设到 ≥ 600s：

• auto（默认）：由模型按内容自动选择画质，耗时介于下列区间。
• low：约 10–40s。
• medium：约 30–90s。
• high 或 2K / 4K 复杂编辑：3–5 分钟，多图融合更久，按最复杂场景预留超时。

接入建议：

• 把 API Key 放在服务端，不要暴露到浏览器。
• 对瞬时网络错误（连接超时、5xx 抖动）可做有限次重试。
• 返回 url 时请尽快将图片转存到自有存储，链接有时效性。

相关页面

• 鉴权
• 语音识别（ASR）与语音合成（TTS）
• OCR 文字识别
• 视觉分割（SAM3 图像 / 视频）