圖像生成

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，而不會二次生成（和二次計費）。生圖慢、易逾時重試，這能防止重複扣費。