画像 API — 生成と編集

ZetaAPI で gpt-image-2 を呼び出して画像を生成・編集。OpenAI Images 互換で、curl / Python / Node のサンプル、マルチパート編集、出力サイズ、課金とタイムアウトを解説します。

更新日 2026-07-26

ZetaAPI の画像エンドポイントは OpenAI Images API と完全互換です。既存の API キーをそのまま使い、gpt-image-2 で画像を生成・編集できます（SDK の変更は不要）。まずブラウザで試すなら、コンソールの 画像 Playground を開いてください。本ページはコードからの呼び出しを解説します。

ベース URL と認証

画像生成は画像専用ドメイン宛に送ります：

https://image.zetaapi.ai

すべてのリクエストに Authorization: Bearer sk-xxxxx を付与します（チャットと同じ API キー）。

画像だけドメインが別な理由：画像生成は非ストリーミングの長時間リクエストで、上流の描画完了まで最大 240 秒かかります。メインドメイン api.zetaapi.ai は CDN の背後にあり、約 120 秒で接続が切断されます。エラーが返りますが、上流では画像が生成済みであり、課金も発生します。画像専用ドメインはオリジンに直結するためこの制限がありません。メインドメイン上で画像生成を自動リトライしないでください。

このドメインが提供するのは /v1/images/generations と /v1/images/edits の 2 つのエンドポイントのみです。それ以外——後述の /v1/chat/completions を使う Gemini 高解像度生成を含む——は引き続き https://api.staging.cosmos-router.com を使用します。

以前の移行案内をお受け取りの場合、そこに記載されていた direct.zetaapi.ai も引き続き有効で、両者は等価です。

ドメインの疎通確認

上記 2 つのエンドポイント以外へのリクエスト（ルートパス / を含む）は、応答を返さずに接続が切断されます。curl には 404 ではなく Empty reply from server や HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR と表示されます。これは意図的なセキュリティポリシーであり、ドメインが利用できないわけではありません。

疎通を確認するには、エンドポイント自体に POST してください（キー不要、クォータも消費しません）：

curl -i -X POST https://image.zetaapi.ai/v1/images/generations \
  -H "Content-Type: application/json" -d '{}'

401 Authorization Required が返れば、DNS・TLS・ゲートウェイはすべて正常です。API キーを求めているだけです。

エンドポイント

画像生成

パラメータ

curl

curl https://image.zetaapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red panda coding at night, neon rim light, 16:9 cinematic banner",
    "n": 1
  }'

Python（openai SDK）

import base64
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://image.zetaapi.ai/v1")

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red panda coding at night, neon rim light, 16:9 cinematic banner",
    n=1,
)

with open("out.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

Node.js（openai SDK）

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxx",
  baseURL: "https://image.zetaapi.ai/v1",
});

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a red panda coding at night, neon rim light, 16:9 cinematic banner",
  n: 1,
});

writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));

レスポンス

{
  "created": 1730000000,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 }
}

既定では b64_json（base64 エンコードの PNG）を返します。"response_format": "url" を渡すと画像 URL を返します。

出力サイズ

アスペクト比は size パラメータではなく、プロンプトで指定してください。

gpt-image-2 は常に約 157 万ピクセルの固定枠で描画します。この枠は引き上げられません — プロンプトに「4K」「3840x2160」と書いてもピクセル数は増えません。一方で**形（アスペクト比）**は制御でき、プロンプトに書いた比率は正確に反映されます。

対応範囲は 1:3 〜 3:1 です。一般的な比率は正確に一致します（16:9 → 1672 × 941）が、限界付近では最も近いサイズになります（1:3 を指定すると実測で約 1:2.9）。ピクセル数は一定なので、どの比率でも料金は変わりません。

size パラメータは OpenAI SDK をそのまま動かすために受け付けますが、無視されます — size: "1024x1536" を指定しても、プロンプトが中立なら正方形が返ります。厳密なピクセルサイズが必要な場合は、最も近い比率で生成してからローカルでリサイズしてください。

さらに高い解像度が必要ですか？ このピクセル上限は gpt-image-2 の上流側の制限で当社では変更できません。最大 17MP まで描画できる Gemini 3 Pro Image をご利用ください。

高解像度：Gemini 3 Pro Image

印刷・大型バナー・壁紙など実解像度が必要な用途には gemini-3-pro-image-preview を使ってください。解像度を指定でき、そのとおりに出力されます。下表は aspect_ratio を指定しない場合の実測値です（比率を変えると幅・高さは変わりますが、ピクセル数の段は同じです）：

このモデルは /v1/images/* では利用できません — 上流プロバイダが chat completions 経由でのみ提供しているためです。Images API との違いは 2 点：

1. POST /v1/chat/completions を呼び、解像度は extra_body で渡します。
2. 画像は data[0].b64_json ではなく、choices[0].message.content の中に Markdown の data URI として返ります。

curl https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [{"role": "user", "content": "Generate an image: a red panda coding at night, neon rim light"}],
    "extra_body": {"google": {"image_config": {"image_size": "4K"}}}
  }'

import base64, re
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://api.staging.cosmos-router.com/v1")

resp = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=[{"role": "user", "content": "Generate an image: a red panda coding at night"}],
    # SDK の extra_body は中身をリクエストのトップレベルに展開しますが、
    # ゲートウェイはトップレベルの `extra_body` を読みます。もう一段包む必要が
    # あり、包み忘れると黙って 1K に落ちます。
    extra_body={"extra_body": {"google": {"image_config": {"image_size": "4K"}}}},
)

# content: "Image generated successfully.\n![image](data:image/png;base64,iVBOR...)"
content = resp.choices[0].message.content
m = re.search(r"base64,([A-Za-z0-9+/=]+)", content or "")
if not m:
    raise RuntimeError(f"no image in response (refused or plain text): {content!r}")
with open("out.png", "wb") as f:
    f.write(base64.b64decode(m.group(1)))

補足：

• 課金はトークン単位（チャットと同じ）。2K は約 1,120 画像トークン（約 $0.06）、4K は約 2,000（約 $0.09）。単価は料金ページを参照。
• 同じ image_config 内で aspect_ratio（例："16:9"）も指定できます。
• 非ストリーミングで、低解像度の gpt-image-2 より遅めです（通常 20〜60 秒、4K ではさらに長くなることも）。注意：これはチャット経路を通るため、ゲートウェイの初回バイト予算は 90 秒です。複雑なプロンプトの 4K は 504 になることがあります。その場合は再試行するか 2K に落としてください。
• 4K の PNG は base64 前で約 19MB、JSON レスポンスは約 25MB になります。クライアントと前段のプロキシがこのサイズを受け取れるか確認してください。

コンソールで 4K 出力

コードは不要です。コンソール → 画像 Playground を開き、解像度で「4K（長辺 3840 以上）」を選んでください。生成・編集の両方のタブで使えます。

• 結果はそのまま 4K で返ります。右上の「ダウンロード」から保存できます
• このモードでは 1 回につき 1 枚生成します
• 最新に近いバージョンのデスクトップ版 Chrome または Edge が必要です。非対応のブラウザではこの項目がグレーアウトされます

これはコンソールの機能です。API から gpt-image-2 を呼び出す場合の出力は、上記のとおり約 157 万ピクセルのままです。

画像編集（edits）

編集は multipart/form-data を使用し、元画像（必須）と任意のマスク（再描画したい領域を指定、透明部分が塗り直されます）をアップロードします：

curl https://image.zetaapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxx" \
  -F model=gpt-image-2 \
  -F 'prompt=中央の四角を青にする' \
  -F image=@source.png \
  -F mask=@mask.png

• 元画像 + マスクの合計 14MB 以内（超過すると 413）
• 形式：png / jpeg
• size は generations と同じ挙動です（受け付けるが無視）。出力サイズを参照

課金・レイテンシ・タイムアウト

• 回数課金：生成 / 編集のたびにそのキーの残高を実際に消費します。倍率は 料金ページ を参照。編集は元画像全体を入力として扱うため、入力トークンが明確に増えます。
• レイテンシ：生成は通常 20–60 秒ですが、複雑なプロンプト（多視点・超精細レンダリング等）やピーク時は 3 分を超えることがあります。クライアントのタイムアウトは 300 秒以上に設定してください。ゲートウェイは上流から 240 秒間、最初のバイトが来ない場合にのみ 504 を返すため、それより早く切断しても待ち損になります。画像編集（/v1/images/edits）は別途：クライアントのタイムアウトは通常アップロード開始から計測されますが、ゲートウェイの 240 秒予算は元画像のアップロード完了後に開始します。アップロード時間 + 300 秒以上（安全側で 400 秒以上）に設定してください。
• 画像レスポンスは非ストリーミングで、完全な結果を一度に返します。

エラーコード

他のエンドポイントと共通です。よくあるもの：

全一覧は API Reference を参照。

関連情報

• ブラウザで試す → コンソールの 画像 Playground
• 一般 API → API Reference
• 課金 → 料金ページ