画像生成

POST /v1/images/generations

OpenAI 互換の画像生成 API です。主力モデルは gpt-image-2。同期と非同期の 2 つのモードに対応しています:

同期 — 画像が生成されるまでリクエストがブロックし、結果を直接返します(低並列・即時用途向け)。
非同期 — 送信後すぐにジョブ ID を受け取り、ポーリングで結果を取得します(大量処理・長時間接続を避けたい場合向け)。

同期: `POST /v1/images/generations`

リクエストパラメータ

パラメータ	型	必須	説明
`model`	string	はい	モデル ID(例: `gpt-image-2`)。
`prompt`	string	はい	画像を説明するプロンプト。
`n`	integer	いいえ	生成枚数。現在は `1` のみ対応(デフォルト 1)。
`size`	string	いいえ	画像サイズ(例: `1024x1024`、`1536x1024`。`gpt-image-2` は対応、一部モデルは非対応)。
`quality`	string	いいえ	画質ヒント(`gpt-image-2` は対応、一部モデルは非対応)。

注意: gpt-image-2 は response_format を受け付けません。ゲートウェイが自動で除外するため、送信不要です。

例

cURL

curl https://api.portal.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow, studio lighting",
    "n": 1
  }'

Python

import openai
 
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.portal.aiin1.ai/v1",
)
 
resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red fox running in snow, studio lighting",
    n=1,
)
b64 = resp.data[0].b64_json   # base64 エンコードの PNG

レスポンス

画像は base64 でインライン返却されます:

{
  "created": 1730000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ]
}

ブラウザ表示時は data:image/png;base64,<b64_json> のように接頭辞を付けます。

非同期: `POST /v1/images/generations/async`

リクエストボディは同期と同一(model / prompt / n / size / quality)ですが、生成を待たずにジョブ ID を即座に返します。バッチ生成や、クライアントが長時間接続を保持したくない場合に使います。

1. 送信

curl https://api.portal.aiin1.ai/v1/images/generations/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow",
    "n": 1
  }'

202 Accepted を返します:

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1730000000,
  "object": "image.generation.async"
}

2. ポーリング: `GET /v1/images/generations/async/{job_id}`

curl https://api.portal.aiin1.ai/v1/images/generations/async/nximg_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status の遷移: queued → processing → succeeded(または failed)。1〜2 秒ごとにポーリングしてください。通常は数秒〜数十秒で完了します。

処理中:

{ "id": "nximg_xxxxxxxx", "status": "processing", "created": 1730000000 }

完了:

{
  "id": "nximg_xxxxxxxx",
  "status": "succeeded",
  "created": 1730000000,
  "data": [
    {
      "url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
      "revised_prompt": "..."
    }
  ]
}

失敗:

{
  "id": "nximg_xxxxxxxx",
  "status": "failed",
  "created": 1730000000,
  "error": { "type": "upstream_error", "message": "generation failed", "code": "..." }
}

url について: 同期(インライン base64)と異なり、非同期では成功時に署名付きダウンロード URL(有効期限約 2 時間)を返します。有効期限内にダウンロード/再保存してください。期限切れの場合は再生成が必要です。失敗したジョブは課金されません。

フィールド一覧

フィールド	説明
`id`	ジョブ ID(`nximg_` 接頭辞)。ポーリングに使用。API キーの組織に紐づき、他者はアクセスできません。
`status`	`queued` / `processing` / `succeeded` / `failed`。
`data[].url`	成功時の署名付き画像ダウンロード URL(約 2 時間有効)。
`data[].revised_prompt`	モデルが修正したプロンプト(空の場合あり)。