GPT Image 2.5 API 接続：生成・編集と Image 2 からの移行

HiAPI で GPT Image 2.5 に接続するには、まず gpt-image-2.5-flare または gpt-image-2.5-sunburst を選び、次に POST /v1/tasks でタスクを送信します。両モデルとも生成と編集に対応しており、image_urls を渡すかどうかでリクエストに参照画像が含まれるかが決まります。

Image 2 から移行する際は、モデル名と入力パラメータの両方を変更する必要があります。 旧版の resolution、size、参照画像フィールド、ルート設定は異なる規約を持っているため、モデル文字列だけを置き換えると適用できないパラメータが残りやすくなります。

以下のコードは 2026 年 9 月 9 日時点の HiAPI オンラインドキュメントに基づいており、リクエストと非同期処理の流れを説明するためのものです。実際の出力と料金はタスク記録に準じます。パラメータの更新は Flare ドキュメント と Sunburst ドキュメント に従ってください。

1 つのモデル ID で生成と編集をカバー

Flare と Sunburst は HiAPI のリクエストフィールドが同じです。どちらかのモデルを選んだら、テキストのみの生成では image_urls を省略します。編集時には 1〜16 枚の参照画像を追加し、プロンプトで変更する内容と保持する内容を指定します。テキストのみの生成で空の配列を送信せず、/edit や /text-to-image のサフィックスを自分で連結する必要もありません。各タスクは 1 枚の画像を出力します。

安定した画像ワークフローが既にある場合は、まず 1 種類のタスクを移行し、元の入力と受け入れ基準を維持するとよいでしょう。2 つのモデルの位置づけについては、まず Image 2 と 2.5 の違い をご覧ください。この記事ではリクエストをどう実装するかに焦点を当てます。

生成リクエストを送信する

以下の例では、正方形のマグカップ商品画像を生成します。JSON を request.json として保存します。quality は後でパラメータを再現しやすいよう明示的に medium に設定し、aspect_ratio はドキュメントに記載されたピクセルサイズ 1024x1024 に設定します。

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

API Key はサーバー側の環境変数 HIAPI_API_KEY に置きます。以下のコマンドはファイルを読み込んで送信し、タスク作成のレスポンスを保存します。HIAPI_REQUEST_ID は、この論理リクエストに対してアプリケーションが生成するものです。同じリクエストをネットワーク問題でリトライする場合は同じ値を使い、入力を変更したり別の画像を作成したりする場合は新しい値を使います。

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

作成に成功したら、created.json の data.taskId からタスク ID を読み取ります。この時点では画像はまだ非同期で生成中です。Idempotency-Key は、同じ論理リクエストの重複送信によって複数のタスクが作成されるのを防ぐためのものです。詳しい規約は タスク作成ドキュメント を参照してください。送信成功を画像の完成とみなさないでください。

同じインターフェースで画像を編集する

以下は独立した Sunburst の編集リクエストです。image_urls 内のプレースホルダーアドレスを、サービスが読み取れる実際の参照画像 URL に置き換え、request.json として保存し、新しいリクエスト ID で送信します。example.com のアドレスはフィールド構造を示すだけであり、そのまま生成に使うことはできません。

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

複数の参照画像を使う場合は、配列の順序で用途を説明します。たとえば 1 枚目が商品、2 枚目が背景を提供します。連続して修正する場合は、前回保存した出力を次のリクエストの参照画像として使います。その場合も毎回新しいタスクであり、新しい修正要求を明示する必要があります。インターフェースが前回の会話や画像を自動的に保持すると仮定しないでください。

透過背景にするには background を transparent に設定し、PNG または WebP を選びます。JPEG は透過チャンネルに対応していません。モデル出力後もエッジと被写体を確認する必要があり、フィールド設定が画像の受け入れ確認に代わるものではありません。

ステータスを照会し、その後にファイルを保存する

GET /v1/tasks/:id はタスクの詳細を返します。queued、handling、archiving はいずれも非終端状態です。success のみが出力が利用可能であることを示し、fail の場合は data.error で失敗情報が提供されます。外側の code: 200 は照会が成功したことだけを示すため、引き続き data.status を判定する必要があります。タスク詳細ドキュメント

以下の Python の例では requests を使い、先ほどの created.json を読み込み、まず 3 秒待ってから 4 秒ごとに照会します。詳細 JSON と最初の画像を保存します。10 分はこの例のローカルな待機上限であり、サービスの SLA を示すものでも、サーバー側のタスクをキャンセルするものでもありません。タイムアウト後も taskId を保持し、後で同じタスクの照会を続けてください。

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

一時出力は output[].expireAt より前にダウンロードするか転送保存する必要があります。本番サービスではリクエストの最上位に callback を設定して終端状態の通知を受け取り、フォールバックとしてポーリングを残せます。コールバックのフィールドは input に入れないでください。コールバックの署名検証と重複通知の処理は 統一非同期 API に従って実装してください。この例には業務キュー、コールバックサービス、完全なネットワークリトライ戦略は含まれていません。

Image 2 からの移行では入力項目を 1 つずつ確認する

旧版 Image 2 はルートが異なるため、移行時にはまず現在どちらを使っているかを確認します。以下は HiAPI ドキュメント間のパラメータ差異であり、他プロバイダーの SDK リクエストをそのまま転用する場合には適用されません。

旧ワークフロー	Image 2.5 での調整
生成と編集で異なる Image 2 モデル ID を使用	完全な Flare または Sunburst の ID に変更し、image_urls の有無で区別する
Standard 編集で input_urls を使用	image_urls に変更する。旧 ext 編集ではすでにこのフィールドを使用していた
Standard / ext で resolution を使用	目標サイズに応じて aspect_ratio の比率またはピクセル列挙を選び直し、resolution は保持しない
Beta 生成で size を使用	ドキュメントがサポートする aspect_ratio のピクセル列挙に変更し、任意のサイズをそのままコピーしない
明示的な route: "beta" / "ext"、またはモデル名にルートサフィックス	2.5 モデルのドキュメントに従ってリクエストを再構築し、旧ルートを踏襲しない
旧版がサポートする 4:5 などの比率	項目ごとに確認する。2.5 の現在の列挙に 4:5 はないため、暗黙に別の比率へ変更しない
デフォルトの品質、サイズ、出力形式に依存	明示的に指定し、出力、料金、下流のファイル処理を再確認する

2.5 の現在の比率オプションは 1:1、3:2、2:3、4:3、3:4、16:9、9:16、auto です。さらに aspect_ratio はドキュメントに記載された 10 個のピクセルサイズを受け付けます。固定サイズが必要な場合は列挙値を選び、文字列の形式だけから任意の widthxheight が使えると推測してはいけません。特に auto は、新しいドキュメントではモデルが適切な構図を選ぶものと説明されており、旧編集ルートの「入力画像に従う」という前提をそのまま引き継ぐべきではありません。

品質オプションは low、medium、high、xhigh、max、auto で、デフォルトは medium です。同じ名前の品質レベルでも、旧モデルと同じ料金や視覚的な結果になるとは限りません。完全な旧プロトコルは Image 2 生成 と Image 2 編集 のドキュメントと照合できます。

エラーと予算を同じ受け入れフローで扱う

送信時の 400 はモデル名、フィールド、列挙値を確認します。402 は残高を確認し、415 は Content-Type を確認します。タスク作成後に fail が発生した場合は data.error を保存して調査し、同じ無効な入力で再送信しないでください。503 は少し待ってからバックオフしながらリトライできます。POST がネットワーク中断により作成されたか判断できない場合は、元の冪等キーを使って重複タスクを避けます。タスク作成エラー説明

コストの確認は HiAPI の現在の料金ページ と具体的なモデルページから始めます。移行の受け入れ時には完全なモデル名、サイズ、品質、参照画像数、リクエスト、出力、実際の請求を記録し、旧 Image 2 の単価を流用したり、他プラットフォームの開始価格を HiAPI の見積もりとみなしたりしないでください。Web 上のサンプル画像は効果の評価に役立ちますが、API の所要時間と請求はそれぞれ実際の記録が必要です。

生成タスク 1 件と編集タスク 1 件を接続、保存、受け入れ確認してから、バッチ処理に拡大してください。Flare モデルページ または Sunburst モデルページ で現在の入口を確認し、対応する Docs に従ってパラメータを維持してください。