GPT Image
GPT Image で画像を生成・編集する方法:パラメータ、レスポンス、注意点。
| 項目 | 値 |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| 画像の生成 | POST /v1/images/generations |
| 画像の編集 | POST /v1/images/edits |
| 非同期タスクの照会 | GET /v1/images/tasks?task_id=… |
| キーのグループ | 「GPT Image 全モデル」。gpt-image-2.5-flare と gpt-image-2.5-sunburst は「GPT 公式ダイレクト(Azure)」でも利用可 |
デフォルトは同期で Base64 の画像を返し、Prefer: respond-async を付けると非同期タスクになります。Codex Plus や Codex Pro などチャットモデルだけのグループのキーで gpt-image-* を呼び出すと 404 が返ります。「GPT 公式ダイレクト(Azure)」グループの画像生成は同期で Base64 を返します。
利用できるモデル
| モデル | モデル ID | quality の段階 | 公式価格 |
|---|---|---|---|
| GPT Image 2.6 Flare | gpt-image-2.6-flare | low / medium / high / xhigh / max | $5 / $30/ 100 万トークン |
| GPT Image 2.6 Sunburst | gpt-image-2.6-sunburst | low / medium / high / xhigh / max | $5 / $30/ 100 万トークン |
| GPT Image 2.5 Flare | gpt-image-2.5-flare | low / medium / high / xhigh / max | $5 / $30/ 100 万トークン |
| GPT Image 2.5 Sunburst | gpt-image-2.5-sunburst | low / medium / high / xhigh / max | $5 / $30/ 100 万トークン |
| GPT Image 2 | gpt-image-2 | low / medium / high | $5 / $30/ 100 万トークン |
選び方:日常的な画像生成は 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 秒です。
GPT Image 2.6(2026-11-04 公開)は 2.5 と同価格で、complexity パラメータと SVG・GIF アニメの出力が加わりました。Flare は速度重視、Sunburst は画質重視のモデルです。参考所要時間(1024x1024 を 1 枚):Flare は low 約 14 秒、high 約 20 秒、xhigh 約 29 秒、max 約 46 秒、Sunburst は low 約 29 秒、high 約 66 秒、xhigh 約 90 秒です。
リクエストパラメータ
生成
POST /v1/images/generations、JSON のリクエストボディ。
| パラメータ | 必須 | 型と制限 | デフォルト | 説明 |
|---|---|---|---|---|
model | 必須 | string | — | 上表の ID のいずれか |
prompt | 必須 | string、32,000 文字以下 | — | 前後の空白を除いて空でないこと |
size | 任意 | auto または WIDTHxHEIGHT | — | 規則は表の下 |
quality | 任意 | auto / low / medium / high | — | 2.5 と 2.6 は xhigh / max も可 |
n | 任意 | integer、1〜10 | 1 | 1 のみ対応のグループあり |
background | 任意 | auto / opaque / transparent | — | 透過には png / webp が必要 |
output_format | 任意 | png / jpeg / webp。2.6 は svg / gif も可 | png | デコード後の形式 |
output_compression | 任意 | integer、0〜100 | 100 | jpeg / webp のみ |
moderation | 任意 | auto / low | — | 安全チェックは無効にならない |
user | 任意 | string | — | エンドユーザーの識別子 |
stream | 任意 | boolean | false | true で Images SSE に切り替え |
response_format | 任意 | string | — | 省略してください |
input_fidelity | 任意 | low / high | — | 互換フィールド。省略してください |
complexity | 任意 | low / medium / high | high | 2.6 のみ。描画前の計画の度合い |
frame_count | 任意 | integer、2〜16 | 9 | 2.6 の gif のみ。フレーム数 |
frame_duration_ms | 任意 | integer、20〜2,000 | 200 | 2.6 の gif のみ。1 フレームのミリ秒数 |
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 ではなく課金先も変わりません。
GPT Image 2.6 のみ。complexity は描画前にモデルがどれだけ計画するかを指定します。追加料金はなく、それ以外の値は 400 になります。output_format: "svg" は SVG を返し、n は 1 のみです。output_format: "gif" は GIF アニメを返します。このとき size は 1 フレームのサイズで、全フレームは 1 辺 3840 以下の 1 枚のシートに並べられるため、auto か 512x512 のような小さいサイズを使ってください(大きいフレームは失敗します。GIF のフレームには上記の総ピクセル数の下限は適用されません)。結果は引き続き b64_json で返るので、デコードして .svg または .gif として保存してください。2.6 の画像には OpenAI の C2PA コンテンツ認証情報が付いており、C2PA の検証ツールで確認できます。
編集
POST /v1/images/edits は上表のすべてのパラメータに加え、参照画像とマスクを受け付けます。ローカルファイルは multipart/form-data を推奨し、JSON(URL / Data URL)も使えます。
| パラメータ | 必須 | 型と制限 | デフォルト | 説明 |
|---|---|---|---|---|
image | 必須 | 1〜16 枚 | — | multipart は image か image[] を繰り返す |
mask | 任意 | アルファチャンネル付き PNG | — | 透明な領域が編集対象 |
markup | 任意 | 透明 PNG のオーバーレイ | — | 2.6 のみ。注釈どおりに編集、mask と併用不可 |
JSON の image は、URL / Data URL 文字列、文字列配列、{"url": …} オブジェクトのいずれかで指定できます。images は読み取らず、プレフィックスなしの base64 や file_id も受け付けません。
**注釈ガイド編集(GPT Image 2.6 のみ)。**最初の入力画像と同じサイズの透明 PNG に丸・矢印・メモを描き、markup として送ります。multipart ではファイルパート、JSON では URL または Data URL です。モデルは注釈の指示どおりに編集します(例:赤い丸に「ここに緑の葉を追加」というメモ)。markup は mask と併用できません。ゲートウェイはアルファチャンネルを保ったまま、最初の画像のサイズに合わせて拡縮します。
リモート 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、complexity、frame_count、frame_duration_ms と編集用の画像 / マスク / markup のみで、その他のフィールドは破棄されます。
レスポンス
同期
| フィールド | 型 | 説明 |
|---|---|---|
created | integer | Unix 秒 |
data[].b64_json | string | Base64 の画像。デコードして output_format の形式で保存 |
usage.input_tokens | integer | 入力トークン(返る場合あり) |
usage.output_tokens | integer | 出力トークン(返る場合あり) |
usage.total_tokens | integer | 合計(返る場合あり) |
usage.cost | number | このリクエストの課金額の人民元額(usage.cost_usd と同じ課金額)。小数点以下最大 6 桁。課金された同期の成功レスポンスには必ず含まれる |
usage.cost_usd | number | このリクエストで残高から実際に差し引かれた米ドル額。小数点以下最大 8 桁で、使用状況のこのレコードと同じ金額 |
usage.currency | string | usage.cost の通貨。常に CNY |
error | object | 失敗時:message、type、code |
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAA..."
}
],
"usage": {
"input_tokens": 42,
"output_tokens": 1760,
"total_tokens": 1802,
"cost": 0.3264,
"cost_usd": 0.048,
"currency": "CNY"
}
}同期の成功レスポンスには、このリクエストの実際の課金額も含まれます。本文の usage.cost・usage.cost_usd・usage.currency、および同じ値のレスポンスヘッダー X-HopBase-Cost・X-HopBase-Cost-USD・X-HopBase-Currency です。生成に時間がかかり(約 40 秒以上)、接続維持のためにサーバーが先に 200 のヘッダーを送っている場合、ヘッダーには課金額が入りません。本文の usage.cost_usd(米ドル、使用記録と一致)または usage.cost(人民元)で照合してください。課金されなかった失敗にはいずれも付きません。詳しくは課金を参照してください。
約 40 秒を超えると、サーバーはまず HTTP 200 を返し、接続を維持するためにボディの先頭へ空白を書き込み続け、完全な JSON は後から書き込まれます。それ以降は生成に失敗しても HTTP ステータスは 200 のままです。成否はボディに error があるかで判断し、読み取りタイムアウトは 300 秒以上にしてください。
ストリーミング(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 | string | タスク ID |
status | string | タスクの状態 |
result_content | string | 完了時:Markdown、画像ごとに 1 行 |
error | string | failed 時のみ:英語の理由、コードなし |
usage.cost | number | このタスクの課金額の人民元額(usage.cost_usd と同じ課金額) |
usage.cost_usd | number | このタスクで残高から実際に差し引かれた米ドル額。使用記録と同じ金額 |
usage.currency | string | usage.cost の通貨。常に CNY |
{
"task_id": "your-task-id",
"status": "completed",
"result_content": "",
"usage": {
"cost": 1.36,
"cost_usd": 0.2,
"currency": "CNY"
}
}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.pngcurl の例では事前に jq をインストールしてください。
SVG、GIF アニメ、注釈ガイド編集(2.6)
# SVG(n は 1 のみ)
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.6-flare",
"prompt": "紙飛行機のフラットな線画アイコン",
"output_format": "svg",
"complexity": "low"
}' \
| jq -r '.data[0].b64_json' | base64 --decode > icon.svg
# GIF アニメ:size は 1 フレームのサイズ
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.6-flare",
"prompt": "しっぽを振る柴犬、ピクセルアート",
"size": "512x512",
"output_format": "gif",
"frame_count": 9,
"frame_duration_ms": 200
}' \
| jq -r '.data[0].b64_json' | base64 --decode > shiba.gif# 注釈ガイド編集:markup.png は注釈を描いた透明オーバーレイ
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-your-key" \
-F "model=gpt-image-2.6-flare" \
-F "prompt=markup の注釈どおりに編集してください" \
-F "image=@plant.png" \
-F "markup=@markup.png" \
-F "output_format=png" \
| jq -r '.data[0].b64_json' | base64 --decode > edited.png編集(複数の参照画像 + マスク)
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[]=@scene.png" \
-F "image[]=@style.png" \
-F "mask=@mask.png" \
-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.6 のモデルのみ対応しています。complexity、markup、SVG / GIF 出力、frame_count、frame_duration_msは 2.6 の 2 モデルのみ対応しています。- GIF 出力では
size: "auto"か512x512のような小さいフレームサイズを使ってください。大きいフレームサイズは失敗します。 background: "transparent"にはpngまたはwebpが必要で、gpt-image-2の透過背景はプレビュー機能です。- 公式のストリーミング用フィールド
partial_images(0〜3)には対応していないため、省略してください。 - 公式 SDK では
streamをデフォルトのfalseのままにしてください。 - ゲートウェイはマスクを 1 枚目の参照画像のサイズに合わせますが、マスク外がピクセル単位で保たれる保証はありません。
result_contentの URL はキーなしで開けるため公開せず、早めに自分のストレージへダウンロードしてください。
- 標準値は OpenAI Images リファレンスと公式の編集リファレンスに従います。
output_compression、moderation、user、response_formatがそのまま渡されるのは同期の JSON 生成と同期の multipart 編集だけで、JSON での編集と非同期タスクではこれらのフィールドは破棄されます。- 1 のみ対応のグループで大きな
nを送ると 400 になり、nが 0 以下なら 1 として扱います。 input_fidelityは互換フィールドで、GPT Image 2 はデフォルトで参照画像を高忠実度で処理します。- 参照画像の枚数は公式側で確認されます。ゲートウェイは枚数を数えず、超えると拒否されるか一部の画像しか使われない可能性があります。
- 公式にはすべての参照画像の合計 MB 上限は明記されておらず、JSON の URL / Data URL 文字列は 1 つあたり 20,971,520 文字までです。
- 4 MiB は転送前の圧縮目標で、アップロードを拒否する閾値ではありません。Base64 にするとデータ量はおよそ 3 分の 1 増えます。
- Data URL の例:
data:image/png;base64,iVBORw0KGgo…。完全なエンコードを送り、MIME タイプを画像と一致させてください。 - 非同期タスクの送信時は残高が 0 より大きいかだけを確認し、金額の予約は行いません。
よくあるエラー
パラメータが不正な場合は生成前に 400 が返り、課金されません。コンテンツの安全チェックで拒否された場合も 400 で課金されず、error.code は safety_rejected です。
| エラー | 対処 |
|---|---|
size must be WIDTHxHEIGHT or auto などの size エラー | 上記の size 規則に従って修正 |
prompt must not be empty | 空でない prompt を指定 |
n must be 1 for this model in the current group | リクエストを分ける |
/v1/images/edits requires at least one image | 参照画像は images ではなく image に入れる |
image download returned HTTP 404 | サーバーから取得できる公開 URL に変更 |
Your request was rejected by the safety system. | プロンプトを書き換えるか参照画像を変更 |
Request body exceeds the size limit (60 MB)(413) | 画像を圧縮するか URL で渡す |
HTTP 200 でボディに error がある | keepalive 開始後の失敗。error.message を確認 |
# 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 出力トークンです。GPT Image 2.6 は低い段階で出力が多く、low 約 820、medium 約 1,450 のため、2.6 の low / medium は 2.5 より高くなります。high 以上は同じです。非同期タスクの実際の課金額は照会結果の usage.cost_usd で確認でき(米ドル。usage.cost は同じ課金額の人民元額)、失敗時は通常 0 です。同期リクエストの課金額はレスポンス自体の usage.cost_usd / usage.cost で確認できます。
単価は上表の各モデルカードとログイン後のモデルカタログを参照してください。
次のステップ
- ほかの画像系列と選び方は画像の概要を参照してください
- ほかの系列:Gemini 画像生成、Seedream、Grok Imagine 画像生成、Kling 画像生成、Midjourney
- 全フィールドは API リファレンスの画像を生成、画像を編集、画像生成タスクを照会を参照してください
- エラーが出たときはエラー早見表を参照してください