GPT Image

デフォルトは同期で Base64 の画像を返し、Prefer: respond-async を付けると非同期タスクになります。チャット用グループのキーで gpt-image-* を呼び出すと 404 が返ります。

利用できるモデル

選び方:日常的な画像生成は Flare が第一候補です。より高品質が必要なら Sunburst を選びます(同じ設定では Flare よりやや遅くなります)。gpt-image-2 は汎用モデルで、ID は gpt-image-2 で、gpt-image-2.0 ではありません。

参考所要時間(1024x1024 を 1 枚)は、low では 2.5 の両モデルとも約 14 秒、high では Flare 約 19 秒、Sunburst 約 37 秒です。

リクエストパラメータ

生成

POST /v1/images/generations、JSON のリクエストボディ。

size の WIDTHxHEIGHT は幅・高さとも 16 の倍数、1 辺 3840 以下、縦横比 3:1 以下、総ピクセル数 655,360〜8,294,400 である必要があります。1K / 2K / 4K の略記は受け付けず、不正な size は生成前に 400 が返り、課金されません。

quality の段階が上がるほど出力トークンが増え、費用も上がります。response_format は何を指定しても b64_json で返り、user は HopBase のアカウント ID ではなく課金先も変わりません。

編集

POST /v1/images/edits は上表のすべてのパラメータに加え、参照画像とマスクを受け付けます。ローカルファイルは multipart/form-data を推奨し、JSON(URL / Data URL)も使えます。

JSON の image は、URL / Data URL 文字列、文字列配列、{"url": …} オブジェクトのいずれかで指定できます。images は読み取らず、プレフィックスなしの base64 や file_id も受け付けません。

リモート URL は 1 枚 25 MiB 以下、Content-Type が image/* で、内部ネットワークのアドレスは使えません。転送前に 4 MiB まで圧縮される場合があり、リクエストボディ全体の上限は 60 MB(超えると 413)です。

非同期

生成または編集のリクエストに HTTP ヘッダー Prefer: respond-async を付けます。ボディは変わらず、これは JSON パラメータではなくヘッダーです。

非同期タスクで保持されるのは model、prompt、n、size、quality、background、output_format、input_fidelity と編集用の画像 / マスクのみで、その他のフィールドは破棄されます。

レスポンス

同期

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802
  }
}

ストリーミング(stream: true)

レスポンスは Images SSE に切り替わります。待機中はコロンで始まる keepalive のコメント行が送られ、最後の data: イベントに完全な Images JSON が入り、[DONE] で終わります。これは OpenAI ネイティブの段階的プレビューイベントではありません。

: hopbase-keepalive

data: {"created":1760000000,"data":[{"b64_json":"iVBORw0KGgoAAA..."}]}

data: [DONE]

非同期タスク

送信すると直ちに 202 Accepted が返り、レスポンスヘッダー Location も同じ照会 URL を指します。

{
  "object": "image.task",
  "task_id": "your-task-id",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=your-task-id"
}

照会は GET /v1/images/tasks?task_id=… のみで、タスク ID をパスに入れる形式には対応していません。pending / processing / retrying は進行中、completed と failed が終了状態です。

{
  "task_id": "your-task-id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

result_content は相対パスなので、https://api.hop-base.com を前に付けてダウンロードします。usage はタスクが completed または failed になると現れ、タスクを作成したキーでのみ確認できます。

例

生成

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "桜の木の下に座る柴犬、和風の水彩画",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

curl の例では事前に jq をインストールしてください。

編集(複数の参照画像 + マスク)

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=マスク部分を花瓶に置き換え、2 枚目の画風に合わせる" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png"

JSON で送る場合はファイルを URL に置き換えます:"image": ["https://example.com/scene.png", "https://example.com/style.png"]、"mask": "https://example.com/mask.png"。

非同期

# 1. 送信して 202 + task_id を受け取る
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "映画のような未来都市の夜景",
    "size": "2048x2048"
  }'

# 2. 最初のレスポンスの task_id でポーリング
curl "https://api.hop-base.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer sk-your-key"

注意事項

• 2K / 4K の大きな画像は、長時間のリクエストが CDN のタイムアウトで切断されないよう非同期を推奨します。
• 同期リクエストでは、クライアントの読み取りタイムアウトを 300 秒以上にしてください。
• size は auto か WIDTHxHEIGHT のみで、段階の略記を送ると 400 になります。
• xhigh / max は 2.5 の 2 モデルのみ対応しています。
• background: "transparent" には png または webp が必要で、gpt-image-2 の透過背景はプレビュー機能です。
• 公式のストリーミング用フィールド partial_images(0〜3)には対応していないため、省略してください。
• 公式 SDK では stream をデフォルトの false のままにしてください。
• ゲートウェイはマスクを 1 枚目の参照画像のサイズに合わせますが、マスク外がピクセル単位で保たれる保証はありません。
• result_content の URL はキーなしで開けるため公開せず、早めに自分のストレージへダウンロードしてください。

よくあるエラー

パラメータが不正な場合は生成前に 400 が返り、課金されません。コンテンツの安全チェックで拒否された場合も 400 で課金されず、error.code は safety_rejected です。

# size: 上表のサイズ規則に従って修正
size must be WIDTHxHEIGHT or auto
size side length exceeds 3840px (4096x2048)
size width and height must be multiples of 16 (1000x1000)
size aspect ratio must not exceed 3:1 (3840x1024)
size total pixel count must be at least 655360 (512x512=262144)
size total pixel count must not exceed 8294400 (3840x3840=14745600)

# prompt が空
prompt must not be empty

# edits JSON: 参照画像は "image" に文字列または {"url": ...} で指定
# "images" は読み取らない
/v1/images/edits requires at least one image
image object is missing the url field
image must be a data URL or an http(s) URL

# リモートの参照画像: image/* を返す公開 URL、1 枚 25 MiB 以下
image download returned HTTP 404
image is too large
image Content-Type is not image/*: text/html
reference image URL must not point to an internal address
image is too large, please compress it to under 4MB and retry

# コンテンツの安全チェック (error.code: safety_rejected)
Your request was rejected by the safety system.

# HTTP 413
Request body exceeds the size limit (60 MB)

課金

トークン単位で課金され、quality が高いほど出力トークンが増えます。1024x1024 の実測で low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 出力トークンです。非同期タスクの実際の課金額は照会結果の usage.cost で確認でき(cost_cny / cost_usd は 1 USD = 6.8 CNY の固定換算)、失敗時は通常 0 です。

単価は上表の各モデルカードとログイン後のモデルカタログを参照してください。

次のステップ

• ほかの画像系列と選び方は画像の概要を参照してください
• ほかの系列:Gemini 画像生成、Seedream、Grok Imagine 画像生成、Kling 画像生成、Midjourney
• 全フィールドは API リファレンスの画像を生成、画像を編集、画像生成タスクを照会を参照してください
• エラーが出たときはエラー早見表を参照してください