画像生成 API

画像 API は OpenAI Images プロトコルと互換です。以下は厳選・確認済みの 8 モデルです。すべて generations で text-to-image を利用でき、/edits は明記されたモデルだけで利用できます。

利用できるエンドポイントは 2 つあります:

• /v1/images/generations - 画像生成。一部のモデルはこのエンドポイントで参照画像も受け付けます
• /v1/images/edits - 下表で明記されたモデル向けの画像編集。OpenAI ネイティブの edits と互換です

エンドポイントと認証

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits

主 Base URL は https://api.icodeeasy.cc です。https://jp.icodeeasy.cc と https://sg.icodeeasy.cc はバックアップ / fallback ドメインで、切り替える場合もパスは同じです。

リクエストヘッダー:

• Authorization: Bearer <your API Key>（必須、sk_ で始まります）
• Content-Type: JSON リクエストでは application/json、ファイルアップロードでは multipart/form-data

/v1 プレフィックスなしの POST /images/generations と POST /images/edits も受け付けられ、同じように動作します。

2 種類のリクエスト形式

API は 2 種類のリクエスト本文形式に対応しています:

1. JSON (Content-Type: application/json): 参照画像を URL または base64 data URL として image_urls に入れます。最も一般的な形式です。
2. multipart/form-data: 参照画像を image[] ファイルとしてアップロードし、他のパラメータをフォームフィールドに入れます。OpenAI ネイティブの edits と同じ使い方で、ローカルファイルのアップロードに向いています。

リクエストパラメータ

• model（必須）: 上表の 8 つの厳選モデル ID のいずれかを指定します。
• prompt（必須）: 英語または中国語の画像説明。上流がコンテンツ安全性レビューを行い、拒否された内容は課金されません。
• n（既定 1）: 画像枚数。課金は画像枚数で加算されます。
• size（既定 1:1）: 出力のアスペクト比。下記を参照してください。auto は 1:1 として扱われ、1536x1024 のようなピクセル指定も受け付けます。
• resolution（既定 1k）: Gemini 2.5 は 1k のみ、表の Gemini 3.x は 1k / 2k / 4k に対応します。gpt-image-2 の tier 選択には使いません。
• quality（gpt-image-2 の課金のみ）: low、medium、high、auto。実際の出力には影響せず、gpt-image-2 の課金価格だけを決めます。Gemini モデルはこのフィールドを無視し、モデル別の固定価格で課金されます。
• image_urls / image_input（任意、JSON）: image-to-image 用の参照画像。最大 4 枚。公開 https://... URL または data:image/...;base64,... を指定でき、混在も可能です。この 2 つのフィールドはエイリアスです。
• image[]（任意、multipart）: image-to-image 用の参照画像ファイル。複数ファイルに対応し、image_urls のファイルアップロード版と同等です。

参照画像の注意: URL は https:// が必須です（http は拒否されます）。base64 は有効な data:image/*;base64, 値である必要があります。

対応比率と解像度

対応する size 比率: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / auto。

gemini-2.5-flash-image は 1k のみです。表の Gemini 3.x は 1k / 2k / 4k に対応します。gpt-image-2 は size で出力比率またはピクセル寸法を指定し、解像度 tier は公開していません。

同期 / 非同期モード

既定の同期モード: 画像生成が完了するまでリクエストを待機し、OpenAI 互換の data[].url を返します。

非同期モード: URL に ?async=1 を追加します（true と yes も受け付けます）。API はすぐに task_id を返し、結果はポーリングで取得します。長い接続を保持したくない場合、進捗処理が必要な場合、バッチ送信する場合に使います。

リクエスト例

最小 text-to-image、同期

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "an orange cat sitting on a windowsill watching the sunset, watercolor style"
  }'

Gemini 3.x で比率と 2K を指定

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

Gemini text-to-image

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a futuristic coffee shop at sunrise, realistic photography",
    "size": "16:9",
    "resolution": "1k"
  }'

画像 URL を使った image-to-image（JSON）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "size": "1536x1024",
    "image_urls": ["https://example.com/photo.png"]
  }'

ローカルファイルをアップロードする image-to-image（multipart）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=make this person 70 years old" \
  -F "size=1536x1024" \
  -F "image[]=@/path/to/photo.png"

複数参照を使った image-to-image（URL + base64 混在）

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "merge these two photos into a poster",
    "size": "4:3",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ]
  }'

非同期送信 + ポーリング

# 1) Submit and get task_id immediately
curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

# 2) Poll until completed
curl "https://api.icodeeasy.cc/v1/images/tasks/d142c93a-..." \
  -H "Authorization: Bearer sk_xxxxxxxx"
# -> {"status":"completed","result_url":"https://...png","cost":0.2,...}

レスポンス構造

Sync success (HTTP 200, OpenAI Images compatible):

{
  "id": "3e0c77bb-9cbd-4c44-9549-bff1b4060623",
  "created": 1781599773,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/3e0c77bb-...-1.png"
    }
  ]
}

Async submit (HTTP 202):

{ "status": "pending", "task_id": "d142c93a-de26-40c9-be62-0de840d10960" }

Async task query (GET /v1/images/tasks/{task_id}):

{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gpt-image-2",
  "cost": 0.2,
  "result_url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/d142c93a-...-1.png"
}

• status: pending / completed / failed
• data[].url / result_url: image URL, usable directly in <img src>
• id / task_id: task ID for support troubleshooting

API は常に URL を返し、response_format: b64_json には対応していません。バイト列が必要な場合は自分で画像をダウンロードしてください。

画像 URL の挙動

data[].url looks like https://api.icodeeasy.cc/v1/images/files/gpt-image-2/YYYYMMDD/<id>-<seq>.png:

• 直接開く: GET は 302 を返し、実際の画像 URL にリダイレクトします
• 強制ダウンロード: ?download=1 を追加します
• 長期利用: リンクは長期的に利用できます
• アクセス制御: このパスは API Key を必要としません。完全なリンク自体が認証情報です。完全な URL を持つ人は誰でも画像をダウンロードできるため、生成結果リンクを公開しないでください。

同期処理とタイムアウト

既定の同期モードでは、画像が準備できるまでリクエストは開いたままになります:

• 推奨するクライアント HTTP タイムアウト: 少なくとも 200 秒
• 1 枚の画像は通常 30〜60 秒かかります。image-to-image、2K、複数画像ではさらに時間がかかる場合があります
• 長い接続で待ちたくない場合は、非同期モード（?async=1）で task_id を取得し、後でポーリングしてください

エラーレスポンス

Error bodies use:

{
  "error": {
    "type": "server_error",
    "message": "...",
    "provider": "icodeeasy.cc"
  }
}

Common statuses:

• 400 invalid_request_error: invalid parameters, unsupported ratio, more than 4 reference images, non-https reference URL, invalid base64, and similar issues
• 401 authentication_error: missing or invalid API Key
• 402 payment_required: insufficient balance or exhausted monthly quota
• 429 rate_limit_error: rate limit exceeded
• 5xx: service temporarily unavailable or generation failed; retry later

失敗したリクエストは課金されず、残高も差し引かれません。

課金

課金は CNY 建ての 画像枚数 x モデル / tier で固定され、トークンとは関係ありません。

gpt-image-2 は quality tier で課金されます:

• low: CNY 0.10 / image
• medium / auto (default): CNY 0.20 / image
• high: CNY 0.40 / image

Gemini 画像モデルはモデル別の固定価格です:

Usage Details では実際の model で記録され、cost_breakdown に image_count、image_cost_rmb、image_urls が含まれるため、履歴からリンクをコピーしたり画像をダウンロードしたりできます。

OpenAI Images API との違い

• Model: 上表の 8 つの厳選モデル ID のいずれかを使用します。gpt-image-1 と dall-e-3 はありません
• Endpoints: すべての厳選モデルが generations に対応し、edits は上表で明記されたモデルだけが対応します
• size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
• resolution: Gemini 2.5 は 1k のみ、表の Gemini 3.x は 1k / 2k / 4k に対応し、gpt-image-2 の解像度 tier は公開していません
• quality: low, medium, high, or auto; billing only, different from OpenAI standard / hd
• response_format: b64_json is not supported; URLs are always returned
• Reference images: 上表で対応が示されたモデルだけが利用でき、対応リクエストでは image_urls / image_input (JSON) または image[] (multipart) をモデル別制限の範囲で使います
• 非同期モード: OpenAI にはこのモードはありません。この API は ?async=1 に対応し、task_id を返し、/v1/images/tasks/{id} をポーリングして結果を取得します
• Task ID: responses include id / task_id for troubleshooting