hiapi API で gpt-image-2.5-sunburst@pro を使う方法：curl、Python、実行可能なリクエスト例

gpt-image-2.5-sunburst@pro は、hiapi 上の gpt-image-2.5-sunburst モデルの Pro ルートです。本ガイドでは、モデル id が具体的に何なのか、受け付ける input フィールドの正確な内容、そのまま実行できる curl/Python のサンプル、そして無人運用の前に必要となる本番向けのパターン（冪等性、コールバック、エラーハンドリング）までを、ゼロから実際に動くリクエストまで順を追って解説します。

事前に用意するもの

• hiapi アカウントと、コンソールで取得した API キー。以下のすべてのリクエストは Authorization: Bearer sk-<your key> で認証します。
• 必要なのはこれだけです。SDK を別途インストールする必要はありません。hiapi 上のすべてのモデルは同じ非同期タスクエンドポイント経由で呼び出されるため、これまでに他の hiapi モデルを呼び出したことがあれば、このリクエストの構造は馴染みのあるものに感じられるはずです。

このモデル固有の唯一のポイント：@pro はルーティング接尾辞であり、ニックネームではありません。hiapi は一部のモデルについて複数の呼び出しモードを公開しており、gpt-image-2.5-sunburst もその一つです。通常のモデル id と @pro 接尾辞付きの id では、受け付ける input フィールドが異なり、異なる料金体系で課金されます。本ガイドは gpt-image-2.5-sunburst@pro に特化した内容です。素の gpt-image-2.5-sunburst id を使うと、別のモード・別のスキーマになります（FAQ を参照）。

最小の実行可能なサンプル

hiapi のすべての生成モデル（画像・動画・音声）は、同じ統一エンドポイント POST /v1/tasks 経由で呼び出されます。model と input を送信すると、すぐに taskId が返り、生成は非同期で実行されます。

gpt-image-2.5-sunburst@pro の場合、input は以下を受け付けます：

フィールド	型	必須	説明
prompt	string	はい	1〜32,000 文字
image_urls	string[]	いいえ	公開された JPEG/PNG/WebP の URL を 1〜16 個。指定するとテキストからの生成ではなく画像からの生成になる（SVG は非対応）
aspect_ratio	enum	いいえ	例：1:1、16:9、9:16、または 1536x1024 のような明示的なサイズ。デフォルトは 1:1
quality	enum	いいえ	low / medium / high / xhigh / max / auto。デフォルトは medium——引き上げる前に下記の本番環境での注意点を確認すること
background	enum	いいえ	transparent、opaque、auto のいずれか。デフォルトは auto
output_format	enum	いいえ	png、jpeg、webp のいずれか。デフォルトは webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "淡い木目のテーブルに置かれた陶器製のハンドドリップ・コーヒードリッパーのミニマルな商品写真、柔らかなスタジオ照明",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

これにより、すぐに taskId が返ります：

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

次に、結果を取得するためにポーリングします：

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

data.status が success になると、画像は data.output[0].url にあります。すぐにダウンロードしてください。この URL には expireAt があり、永続的な外部リンク参照には適していません。

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "淡い木目のテーブルに置かれた陶器製のハンドドリップ・コーヒードリッパーの "
                      "ミニマルな商品写真、柔らかなスタジオ照明",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

本番運用のパターン

ポーリングとコールバック。上記のループはスクリプトや低トラフィックの用途には問題ありません。サーバーサイドのあらゆるシナリオでは、ポーリングよりもコールバックを優先しましょう。同じリクエストに callback オブジェクトを追加します——

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url は HTTPS である必要があり、when: "final"（現在サポートされている唯一の値）は成功時と失敗時の両方で一度だけ通知します。ポーリングループも不要で、無駄なリクエストも発生しません。hiapi はコールバックを複数回配信する可能性があるため、受け取り側で taskId による重複排除を行ってください。

冪等性。POST /v1/tasks に Idempotency-Key ヘッダを追加します（255 バイト以下の任意の文字列、例えば注文 id など）。ネットワークタイムアウトでクライアントが同じ送信をリトライした場合、プラットフォームは2つ目のタスクを作成・課金する代わりに、元の taskId を返します（レスポンスヘッダに Idempotent-Replay: true が付きます）。このキーのスコープはあなたのアカウントで、24 時間後に失効します。異なるリクエストボディで再利用すると、黙って新しいタスクを作成するのではなく 422 IDEMPOTENCY_KEY_MISMATCH を返します。したがって、不一致はリトライロジックを確認すべきシグナルであり、盲目的にリトライしてはいけません。

認証エラー。形式が不正または誤った API キーは、タスク作成前に 401 と permission_denied エラーコードで即座に失敗します：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

これが表示された場合、原因はほぼ常にキー自体（環境変数の設定ミス、キーの失効、sk- プレフィックスの欠落）であり、リクエストボディではありません。キーが修正されるまで、リトライ不可として扱ってください。

quality について。quality のデフォルトは medium で、これは妥当な初期値です。引き上げるとコストと生成時間の両方が増加するため、特定の prompt がそのレベルでも確実に成功することを自身のテストで確認できた場合にのみ、high/xhigh/max に引き上げてください。

関連ページ

• gpt-image-2.5-sunburst モデルページ——このモデルシリーズの機能、サンプル出力、利用可能なすべてのモード。
• 統一非同期 API ドキュメント——すべての hiapi 生成モデルが共有する /v1/tasks の完全な契約（冪等性、コールバック、ステータスコード）。
• 認証ドキュメント——API キーの作成と管理の方法。
• gpt-image-2.5-sunburst API ガイド——ベース（@pro でない）モードを使いたい場合、その独立した resolution ベースのスキーマについて詳しく解説しています。
• 料金——quality ティアごとの現在の1枚あたりのコスト。

FAQ

gpt-image-2.5-sunburst@pro と gpt-image-2.5-sunburst は別のモデルですか？ 同じモデルシリーズの異なるルートです。素の gpt-image-2.5-sunburst id（およびその /text-to-image モード）は resolution フィールド（1K/2K/4K）を受け付け、quality や image_urls フィールドはありません。@pro はこれを quality ティアに置き換え、さらにオプションの image_urls を追加します。そのため、同じ呼び出しで品質ティアを制御したい場合や画像からの生成を行いたい場合は、このルートを使用してください。

参照画像は必要ですか？ いいえ。テキストからの生成では image_urls を完全に省略します。公開画像 URL を 1〜16 個指定すると、参照画像に基づいて出力を条件付けするモードに切り替わります。

API キーなしでこのモデルを使えますか？ いいえ。すべてのリクエストには、あなたのアカウントの実際の hiapi API キーを含む有効な Authorization: Bearer ヘッダが必要です。未認証やキー不要のティアはありません。

料金はいくらですか？ 料金は quality ティアによって異なり、ここに重複して記載するのではなく料金ページで最新の状態に保たれています。スケール時のコストを見積もる前に必ず確認してください。

コールバックが届かない場合はどうすればよいですか？ コールバックの配信は即時性が保証されておらず、hiapi は配信をリトライする可能性があります（そのため taskId による重複排除を行ってください）。厳格な上限が必要な場合は、タイムアウト後に GET /v1/tasks/:id へのフォールバックポーリングを用意し、コールバックを無期限に待たないようにしてください。

送信時のエラーではなく fail ステータスになるのはなぜですか？ 送信（200/taskId を返す）はリクエストが受け付けられたことだけを意味します。生成自体は非同期で失敗する可能性があります。ポーリング後またはコールバック経由で data.status を確認し、再送信する前に data.error で原因を確認してください。