HiAPI API で gpt-image-2.5-sunburst/image-to-image を使う方法：curl と Python

このエンドポイントにおける画像から画像への変換機能

gpt-image-2.5-sunburst/image-to-image エンドポイントはシンプルな約束事に従います。参照画像と自然言語の編集指示を送信すると、モデルはその指示を適用しつつ参照画像に基づいた新しい画像を返します。テキストから画像への生成とは異なり——テキストから画像はゼロから始まり、プロンプトに完全に依存します——画像から画像への変換は参照画像を視覚的なコンテキストとして扱います。構図、被写体、スタイル、色彩の手がかりは、指示が明確に変更を求める場合を除いて引き継がれます。

このため、既存の素材があり、製品写真のスタイル変更、光や背景の変更、被写体の外観の調整、既存の概念のバリエーション生成など、制御された変換を行いたい場面に適しています。元素材がなく最大の創作自由度を求める場合はテキストから画像を選び、既存画像への忠実性が新規性より重要なら画像から画像を選びます。

開発者が覚えておくべき重要なメンタルモデル：参照画像は入力制約であり、編集指示は差分です。良い指示は、存在すべきすべてのものではなく、何を変更すべきかを記述します。「背景をクリーンなスタジオグラデーションに置き換え、被写体とその影は維持する」は、完全なシーン記述よりも効果的です。参照画像がすでにシーンを提供しているからです。以下のリクエスト構造の説明を読む際は、この点を念頭に置いてください——リクエストボディは小さいですが、指示の品質が出力品質を決めます。

事前準備とリクエスト構造

初回呼び出しの前に、3つのものを用意してください：

• API キー：HiAPI アカウントから発行されます。ソースコードではなく環境変数に置いてください。
• ベース URL：HiAPI API の base URL です。ダッシュボードまたは API リファレンスドキュメントを参照してください。
• エンドポイントパス：gpt-image-2.5-sunburst/image-to-image。

各リクエストは JSON ボディと Authorization ヘッダーを伴う POST リクエストです。概念的には、リクエストボディは3つの論理部分から構成されます：

1. モデル選択——このエンドポイントのモデル識別子。ゲートウェイが呼び出しを正しくルーティングするために必要です。
2. 入力——参照画像（ホストされた URL または base64 データ文字列）と編集指示テキスト。
3. 出力制御——エンドポイントドキュメントに記載された任意のパラメーター（サイズや数量など）。公式リファレンスドキュメントに記載されているパラメーターのみ使用し、名前を推測しないでください。

規律に関する注意点：これはホストされたエンドポイントであるため、どのフィールドが受け入れられるかは現在の API リファレンスドキュメントによって定義され、他の画像 API から推測すべきではありません。不明な場合は、まず最小限の有効なリクエストボディ（model、image、prompt）を送信し、200 レスポンスが返ることを確認してから、任意フィールドを1つずつ追加してください。こうすれば、各障害を単一の変更に帰属させることができ、一度に組み立てたリクエストボディによる混乱を避けられます。

参照画像と編集指示の送信

参照画像の提供方法は2つサポートされており、トレードオフは主に画像バイトをどこに置くかにあります。

ホストされた URL

画像が公開アクセス可能な場合、その URL を直接渡します。リクエストボディが小さくシリアライズが速いため、開発段階で最も簡単な選択です。URL はサービスが直接取得できる必要があります——認証の背後にあってはならず、リダイレクトチェーンであってもならず、画像を含む HTML ページであってもなりません。

Base64 データ

画像がローカルにあるかプライベートなリソースの場合、エンコードしてインラインで送信します。Base64 はリクエストボディを約3分の1膨らませるため、ソース画像が大きいとサイズ制限に近づく可能性があります。上限に近い場合は、エンコード前にダウンサンプリングしてください。

形式とサイズの落とし穴

• 主流の形式（PNG、JPEG、WebP）を使用し、ファイル拡張子が実際のバイトと一致することを確認してください。
• 過大な画像はリクエストが拒否される最も一般的な原因です。適切なサイズのソース画像を選んでください。1回の編集を駆動するのにフル解像度の素材は通常不要です。
• base64 文字列を自分で結合する場合、API リファレンスドキュメントの例に data URI プレフィックスが含まれている場合にのみ追加し、そうでなければ外してください。これら2つの慣習を混在させることが「invalid image」エラーのよくある原因です。

編集指示の書き方

出力品質の成否は指示にかかっています。何を変更するかを具体的に述べ、何を保持するかを明確に述べてください。対象（「ジャケット」）、変換（「濃いネイビーに再着色」）、制約（「モデルのポーズと既存の影を維持」）を明記します。1つの指示に無関係な複数の編集を積み重ねることは避けてください——独立した変更が必要な場合は複数の呼び出しに分割すれば、各結果の評価も容易になります。

実行可能な curl リクエスト

以下はターミナルで完全に実行できるリクエストです。キーと画像のプレースホルダーを自分の値に置き換えてください。

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.5-sunburst/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": "背景を柔らかなニュートラルなスタジオグラデーションに置き換える。被写体、そのポーズ、既存の影は変更しない。"
  }'

項目ごとの説明：

• -X POST——この操作は新しい画像を作成するため、POST を使用します。
• URL はベース URL とエンドポイントパスを結合して構成されます。ベース URL を環境変数に置くと環境の切り替えが容易です。
• Authorization: Bearer ...——API キーです。HIAPI_API_KEY としてエクスポートすれば、シェル履歴やログに現れません。
• Content-Type: application/json——ボディは JSON です。このヘッダーの欠落は、混乱を招く 4xx レスポンスのよくある原因です。
• model——エンドポイントの識別子です。ドキュメントと完全に一致させてください。
• image——参照画像です。ここではホストされた URL です。base64 に切り替える場合は、データ文字列またはローカルでエンコードした変数に置き換えてください。
• prompt——編集指示です。変更内容と保持すべき内容のみを記述してください。

手動でエンコードせずにローカルファイルでテストしたい場合、ほとんどのシェルでは小さなスクリプトや jq で JSON を構築できます。重要なのは、最終的なリクエストボディがこれらのフィールドを含む有効な JSON であることです。

同じリクエストを Python で実装

Python 版はリクエストボディを完全に同一に保ち、レスポンスを並べて比較できるようにします。requests を使用します：

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": (
        "背景を柔らかなニュートラルなスタジオグラデーションに置き換える。"
        "被写体、そのポーズ、既存の影は変更しない。"
    ),
}

response = requests.post(
    f"{base_url}/gpt-image-2.5-sunburst/image-to-image",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

2点注目に値します。第一に、json=payload はコンテンツタイプを設定し、ボディを自動でシリアライズするため、手動 JSON 構築に関するエラー群を排除します。第二に、timeout=120 は意図的です。画像生成は即時完了せず、永遠に待つクライアントはクリーンに失敗するクライアントより悪いです。ワークロードに合わせてタイムアウトを調整してください。ただし必ず設定してください。

ローカルファイルに切り替えるには、そのバイトを読み取り、base64 エンコードし、結果を image に代入します。ホストされた URL を使用する場合は文字列をそのままにします。curl と Python の呼び出しが同一構造を返せば、両者が同じ動作をすることが確認でき、どちらの方式でも構築を続けられます。

よくあるリクエスト失敗のトラブルシューティング

ほとんどの失敗は4つのカテゴリに分類できます。以下の順序で一つずつ確認してください。各カテゴリが次のカテゴリを装う可能性があるためです。

認証エラー

401 または 403 は、ほぼ常にキーが欠落しているか、形式が誤っているか、期限切れであることを意味します。ヘッダーが厳密に Authorization: Bearer <key> であること、コピー＆ペーストによる余分な引用符や改行が入っていないこと、リクエストを実行するシェルまたはプロセスでその環境変数が実際に設定されていることを確認してください。curl では動作するが Python では動作しないキーは、通常、壊れたキーではなく未設定の変数を指します。

リクエストボディの形式エラー

検証情報を伴う 400 は、通常、JSON が不正または必須フィールドが欠落していることを意味します。送信前にボディを整形して出力し、model がエンドポイント識別子と一致すること、編集指示フィールドの名前がドキュメントと一致することを確認してください。curl で JSON を手書きする場合、末尾のカンマと単一引用符が典型的な犯人です。Python の json= はこれらの問題を回避します。

画像入力の不正または過大

サービスが画像を拒否する場合、3つのことを確認してください：URL が公開取得可能で画像を返していること（リダイレクトやエラーページではないこと）、形式がサポートされていること、リクエストボディがドキュメントで規定されたサイズ制限を超えていないこと。base64 入力の場合、エンコードがクリーンで、data URI プレフィックスの慣習がリファレンス例と一致することを確認してください。不明な場合は、まずダウンサンプリングしてから再試行してください——より小さなソース画像はこれらのエラーの相当部分を解決します。

タイムアウトと一時的障害

長時間の生成はクライアントタイムアウトを超える可能性があり、429 または 5xx レスポンスはレート制限または一時的なサーバー問題を示します。これらをクライアントエラーと区別してください：400 をそのまま再試行しないでください。ただし 429 や 503 はバックオフ付き再試行に適しています。各失敗のステータスコードとレスポンスボディを記録してください——明確なエラーログはトラブルシューティングを推測から項目別チェックに変えます。

スクリプトから再利用可能なクライアントへ

使い捨てスクリプトはエンドポイントが機能することを証明します。小さなラッパーはそれをパイプラインで安定して動作させます。呼び出しを関数でラップし、リクエスト、タイムアウト、制限付き再試行戦略の3つを担当させます。

import os
import time
import requests

class ImageEditClient:
    def __init__(self, base_url: str, api_key: str, timeout: int = 120):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.timeout = timeout

    def edit(self, image: str, prompt: str, retries: int = 3):
        url = f"{self.base_url}/gpt-image-2.5-sunburst/image-to-image"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        payload = {
            "model": "gpt-image-2.5-sunburst/image-to-image",
            "image": image,
            "prompt": prompt,
        }
        last_error = None
        for attempt in range(retries):
            try:
                resp = requests.post(
                    url, headers=headers, json=payload, timeout=self.timeout
                )
            except requests.Timeout as err:
                last_error = err
                time.sleep(2 ** attempt)
                continue
            if resp.status_code in (429, 500, 502, 503, 504):
                last_error = RuntimeError(f"transient {resp.status_code}: {resp.text}")
                time.sleep(2 ** attempt)
                continue
            if resp.status_code >= 400:
                raise RuntimeError(f"request failed {resp.status_code}: {resp.text}")
            return resp.json()
        raise RuntimeError(f"exhausted retries: {last_error}")

設計上の選択はコード自体より重要です。再試行はタイムアウトと一時的なステータスコードにのみ適用し、4xx クライアントエラーには決して適用しません。形式が誤ったリクエストボディを再試行するとクォータを浪費するだけだからです。指数バックオフはレート制限されたパイプラインがエンドポイントを繰り返し圧迫するのを防ぎます。クライアントエラーはレスポンスボディ付きで即座にスローされ、呼び出し元はサービスが何に反対しているかを正確に確認できます。モデル識別子を一箇所に集中させることは、将来他の画像エンドポイントに切り替える際にコードベース全体を探し回るのではなく1行変更するだけで済むことを意味します。

この上に、各試行の構造化ログを追加し、下流のコンシューマーがレスポンスを使用する前にサイズ/形状チェックを行ってください。同じゲートウェイ上の他の画像モデルを探索する準備ができたら、HiAPI モデルカタログはクライアントを書き直さずに各エンドポイントを比較するのに最適な場所です。