画像生成

POST /v1/images/generations

テキストプロンプトから画像を生成します。OpenAI 互換 —— OpenAI の画像 API と同じエンドポイント・同じ SDK 呼び出し(client.images.generate)で、1つの API key により OpenAI、Google、Alibaba、ByteDance の画像モデルへルーティングします。

リクエストボディ

利用可能なモデル

モデルの利用可否はデプロイ環境によって異なります。最新でコンプライアンスに対応した一覧は次から取得します: GET /v1/images/models で取得できます。代表的なモデル:

どのモデルを選べばいいか迷ったら？必要な条件で選びましょう

Price：token · $in→$out /1M = 使用量に基づく課金（OpenAI / Google）。$/image = 生成画像 1 枚あたりの定額。Response：b64 · url ✓ のモデルは、署名付きのベンダーホスト URL を返すこともできます（response_format: "url"、有効期間 ~24 h）。ダウンロード速度はベンダーに依存します：Alibaba の URL はグローバル高速化 CDN を経由し（中国本土を含めどこでも高速）、ByteDance seedream の URL はシンガポールのオブジェクトストレージから配信されます（海外クライアントには高速、中国本土からは低速）。b64 only のモデルは response_format: "url" を 400 url_not_supported で拒否します。Edit (i2i) = すべてのモデルが image-to-image に対応します（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 is supported only where the upstream itself hands back a CDN URL — currently the Alibaba and ByteDance families (qwen-image*, wan*, seedream*); the image downloads from the vendor's CDN via a pre-signed URL valid ~24 hours. OpenAI and Google models (gpt-image*, gemini*) are b64-only: requesting url there returns 400 url_not_supported — rejected before generation, nothing is billed. Check per model via the supports_url field of GET /v1/images/models, or the model table above.

Complete example — url mode

Generate with response_format: "url", read data[0].url from the response, then download the image from the vendor's CDN — a full round-trip you can paste into a terminal:

# 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..."

The URL is pre-signed — anyone with it can download, no auth header needed — and expires in ~24 hours: fetch promptly and re-host the file if you need it long-term. Typical end-to-end: ~15–30 s generation + sub-second CDN download.

Latency, large responses & timeouts

Generation time varies by model: qwen-image-2.0 typically returns in ~5–10 s, while wan2.7-image and seedream-class models take ~15–30 s (longer at 2K+ sizes). The gateway allows up to 180 s per request and returns 504 generation_timeout beyond that — this API itself never returns 408.

The default response_format=b64_json embeds the full image in the response body (2–3 MB of base64 for large models). On slow or long-haul client links, downloading that body can add minutes and trip your HTTP client's or relay gateway's own timeout — typically surfaced on your side as 408 or a timeout error.

課金

成功時(HTTP 200)のみ課金されます。ほとんどのモデルは画像単位(枚数 × 単価)で課金されます。トークン使用量を返す OpenAI gpt-image-* モデルはトークン単位で課金されます。各課金は 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 での再リクエストは、2回目の生成(および課金)を行わず 409 を返します。画像生成は遅くリトライが発生しやすいため、これにより二重課金を防ぎます。