图像生成

POST /v1/images/generations

根据文本提示词生成图像。OpenAI 兼容 —— 与 OpenAI 图像 API 同一端点、同一 SDK 调用(client.images.generate),一把 API key 即可路由到 OpenAI、Google、阿里、字节的生图模型。

请求体

可用模型

模型可用性取决于你的部署。通过 GET /v1/images/models获取实时、合规感知的完整列表。代表性模型:

不确定用哪个模型？按需求来选

Price：token · $in→$out /1M = 按用量计费（OpenAI / Google）；$/image = 每张生成图像固定收费。Response：b64 · url ✓ 模型还可返回预签名的厂商托管 URL（response_format: "url"，有效期 ~24 h）。下载速度取决于厂商：Alibaba 的 URL 走全球加速 CDN（各地都快，含中国大陆）；ByteDance seedream 的 URL 由新加坡对象存储提供（对海外客户端快，从中国大陆慢）。b64 only 模型会以 400 url_not_supported 拒绝 response_format: "url"。Edit (i2i) = 每个模型都支持图生图（传入 image 字段）；该数值为最大参考图数量。

图生图(编辑)

在同一请求里加 image 字段,即可编辑/参考一张输入图,而非仅凭文本生成。gpt-image、gemini-*-image、qwen-image / wan2.7、seedream 均支持(每个模型对输入图张数有上限)。图片用 base64 或 data URI 传;多张参考图传数组。

curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "add a small red party hat on the main subject",
    "image": "'"$(base64 -i input.png)"'"
  }'

响应格式

设置 response_format: b64_json 返回 base64 图像字节(默认); url 在上游支持时返回可下载 URL。响应结构与 OpenAI images API 一致:{ created, data: [{ b64_json | url }] }。

url 仅在上游本身返回 CDN 链接时可用——目前为阿里与字节两个家族 (qwen-image*, wan*, seedream*);图片经厂商 CDN 以预签名 URL 下发,约 24 小时有效。OpenAI 与 Google 系模型 (gpt-image*, gemini*) 只支持 b64:对它们请求 url 会返回 400 url_not_supported (生成前即拒绝,不产生任何计费)。可通过 supports_url 字段逐模型判断( GET /v1/images/models 返回),或直接看上方模型总表。

完整示例——url 模式

带 response_format: "url" 发起生成,从响应中读取 data[0].url,再从厂商 CDN 下载图片——一次可直接粘贴到终端的完整调用:

# 1) Generate — ask for a URL instead of inline base64
curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "prompt": "a serene mountain lake at sunrise",
    "response_format": "url"
  }'

# → 200 in ~15–30 s. Tiny JSON body — no image bytes inline:
{
  "created": 1783064343,
  "data": [
    {
      "url": "https://dashscope-463f.oss-accelerate.aliyuncs.com/1d/8a/20260703/xxxx.png?Expires=1783151704&OSSAccessKeyId=LTAI...&Signature=bvTa..."
    }
  ]
}

# 2) Download from the vendor CDN — the URL is pre-signed, no auth header needed
curl -o out.png "https://dashscope-463f.oss-accelerate.aliyuncs.com/1d/8a/20260703/xxxx.png?Expires=1783151704&OSSAccessKeyId=LTAI...&Signature=bvTa..."

URL 为预签名链接——持有链接即可下载,无需任何鉴权头——约 24 小时后过期:请及时下载,需长期保存请转存到你自己的存储。典型端到端耗时:生成 ~15–30 秒 + CDN 下载亚秒级。

延迟、大响应体与超时

生成耗时因模型而异:qwen-image-2.0 通常 ~5–10 秒返回,wan2.7-image 与 seedream 系列约 15–30 秒(2K+ 尺寸更久)。网关单请求上限 180 秒,超出返回 504 generation_timeout——本 API 自身不会返回 408。

默认 response_format=b64_json 会把完整图片内嵌在响应体中(大图约 2–3 MB base64)。客户端链路较慢或跨境时,下载响应体可能额外耗时数分钟,进而触发你自己的 HTTP 客户端或中转网关的超时——通常在你这一侧表现为 408 或 timeout 错误。

计费

仅成功(HTTP 200)才计费。多数模型按图计费(张数 × 单价);返回 token 用量的 OpenAI gpt-image-* 按 token 计费。每笔扣费都记录 request_id、模型、费用,可追溯。

示例 — curl

curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "a serene mountain lake at sunrise, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

示例 — Python(OpenAI SDK)

from openai import OpenAI
import base64

client = OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

resp = client.images.generate(
    model="qwen-image-2.0",
    prompt="a serene mountain lake at sunrise, photorealistic",
    n=1,
    size="1024x1024",
)
# Default response_format is b64_json
img = base64.b64decode(resp.data[0].b64_json)
with open("out.png", "wb") as f:
    f.write(img)

示例 — Node(OpenAI SDK)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://synthorai.io/v1",
  apiKey: process.env.SYNTHORAI_API_KEY,
});

const resp = await client.images.generate({
  model: "seedream-4-0-250828",
  prompt: "a serene mountain lake at sunrise, photorealistic",
  n: 1,
});
fs.writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));

幂等

传 X-Idempotency-Key 请求头让重试安全:相同 key 的重复请求返回 409,而不会二次生成(和二次计费)。生图慢、易超时重试,这能防止重复扣费。