이미지 생성

POST /v1/images/generations

텍스트 프롬프트로 이미지를 생성합니다. OpenAI 호환 — OpenAI의 이미지 API와 동일한 엔드포인트 및 SDK 호출(client.images.generate)을 사용하며, 단일 API 키로 OpenAI, Google, Alibaba, ByteDance의 이미지 모델로 라우팅됩니다.

요청 본문

사용 가능한 모델

모델 사용 가능 여부는 배포 환경에 따라 다릅니다. 실시간, 규정 인식 목록은 다음을 통해 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 모델은 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의 이미지 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, model, cost와 함께 기록됩니다.

예제 — 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 헤더로 재시도를 안전하게 만듭니다: 동일한 키로 반복된 요청은 두 번째로 생성(및 과금)하는 대신 409를 반환합니다. 이미지 생성은 느리고 재시도가 잦으므로, 이를 통해 이중 과금을 방지합니다.