画像生成（非同期のジョブ方式）。テキストから画像はプロンプトだけで動きます。画像から画像は `image` に参照画像（URL、data: URI、base64）を渡します。呼び出すと即座にジョブ ID が返り（HTTP 202）、GET /v1/images/jobs/{id} をポーリングして結果を受け取ります。1:1、3:4、2:3、9:16、4:3、3:2、16:9 の 7 種類の比率に対応し、選んだ比率でネイティブに描画するため被写体が切れません。
Playground で試す →認証
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
コンソールで API Key を作成すると利用を開始できます。
リクエストボディ
| パラメータ | 種別 | 必須 | 説明 |
|---|---|---|---|
| model | string | はい | モデル ID。gpt-image-2 を指定してください。 |
| prompt | string | はい | 画像を説明するテキストプロンプト。 |
| size | string | いいえ | 出力の画面比率。1:1、3:4、2:3、9:16、4:3、3:2、16:9 のいずれかの比率を渡すのがおすすめで、モデルはその比率でネイティブに描画するため被写体が切れません。ピクセル指定（1024x1024、1024x1536、1536x1024 など）も受け付けます。既定は 1:1（正方形）です。 |
| n | integer | いいえ | 生成する画像の枚数。既定は 1 です。 |
| image | string | いいえ | 画像から画像：参照画像を公開 URL、data: URI、生の base64 のいずれかで渡します。指定すると、人物や被写体を保ったままの本物の画像から画像として、選んだサイズ・比率で生成します。/v1/images/edits の呼び出しと同等です。 |
| images | array | いいえ | 複数枚の参照画像（最大 8 枚。被写体の一貫性を保つには 4 枚以下を推奨）。文字列の配列か、[{"image_url": "..."}] というオブジェクトの配列で渡します。各要素は公開 URL、data: URI、base64 のいずれかです。複数参照の画像から画像として動作し、複数の参照の被写体とスタイルを融合します。/v1/images/edits の複数画像入力と同等です。1 枚だけなら上の image フィールドでも構いません。 |
リクエスト例
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"model": "gpt-image-2", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded, then read data[].url
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'レスポンス
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "gpt-image-2"
}画像から画像（Image-to-Image）
画像から画像：`image` に参照画像（公開 URL、data: URI、生の base64）を渡すと、人物や被写体を保ったままの本物の i2i として実行され、選んだサイズ・比率で描き直します。/v1/images/edits の呼び出しと同等です。
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "gpt-image-2", "prompt": "背景を星空に差し替えてください", "image": "https://example.com/ref.png", "size": "3:4"}'画像ジョブ（送信 → 結果をポーリング）
画像の生成には通常 1〜3 分かかるため、画像エンドポイントはジョブ方式のみです。リクエストを送ると即座にジョブ ID が返り（HTTP 202）、その ID で結果をポーリングします。サーバーは再起動をまたいでも生成を続けるので、画像が失われることはありません。文字から画像でも画像から画像でも同じです。（従来の "async": true は不要になりました。受け付けますが無視されます。）
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "gpt-image-2", "prompt": "余白を大きくとった水墨画風のポスター", "size": "3:4"}'{ "id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "gpt-image-2" }curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "succeeded",
"model": "gpt-image-2",
"data": [{ "url": "https://img.nezhagate.com/i/9f86d081a8....png" }]
}status は queued / processing / succeeded / failed のいずれかです。成功するとレスポンスに data[].url が入ります。ジョブをポーリングできるのは、それを作成したアカウントだけです。画像エンドポイントは常に非同期で、送信するとジョブ ID が返ります。"async": true は後方互換のためだけに受け付け、無視します。
エラーコード
| Code | 説明 |
|---|---|
| 401 | API Key が欠落または無効 |
| 402 | 残高不足または Key が上限超過 |
| 400 | モデルまたはパラメータが非対応 |
| 429 | 上流のレート制限 |
| 502 | すべての上流回線が失敗 |
