HiAPI
Ja
ブログ

チュートリアル

hiapi API で gpt-image-2.5-sunburst を使う方法：curl、Python、そして利用可能なリクエスト例

最小リクエスト、完全なパラメータリファレンス、そして本番環境にデプロイする前に必須の callback/冪等パターン。

Sep 10, 2026
hiapi API で gpt-image-2.5-sunburst を使う方法：curl、Python、そして利用可能なリクエスト例

gpt-image-2.5-sunburst で画像を生成・編集するには、プロンプトを含むタスクを POST /v1/tasks に送信し、タスクが完了するまで GET /v1/tasks/<id> をポーリングする（またはコールバックを受け取る）と、data.output[0].url から画像 URL を読み取れます。本ガイドでは、最小リクエスト、完全なパラメータセット、そして本番稼働前に必要な本番パターン（コールバック、冪等性、エラーハンドリング）を扱います。

前提条件

hiapi API キーが必要です。コンソールで作成してください。すべてのリクエストは Authorization: Bearer sk-<your-key> で認証します。ブラウザからキーなしで呼び出す無料枠の方法も、キー不要の方法もありません。以下のすべての例は、すでにキーを持っていることを前提としています。

最小の動作例

gpt-image-2.5-sunburst/text-to-image は input 内に prompt だけを必要とします。アスペクト比はデフォルトで auto、解像度はデフォルトで 1K です。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "大理石のカウンターの上に置かれたセラミック製エスプレッソカップのミニマルな商品写真、柔らかな朝の光"
    }
  }'

すぐにタスク id が返されます：

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

結果をポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

同じ往復フローの Python 版：

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "大理石のカウンターの上に置かれたセラミック製エスプレッソカップのミニマルな商品写真"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url は一時ストレージを指します。レスポンスには expireAt（Unix 秒）が含まれます。その期限までにバイト列をダウンロードして永続化してください（自前のストレージ、S3、R2 など）。恒久的なリンクとして扱わないでください。

完全なパラメータリファレンス

gpt-image-2.5-sunburst には 2 つのモデル id があります。gpt-image-2.5-sunburst/text-to-image はプロンプトからの生成に、gpt-image-2.5-sunburst/image-to-image は参照画像の編集や合成に使用します。どちらも同じフィールドを受け付けますが、違いは image_urls が image-to-image では必須であり、text-to-image では使用されない点です：

フィールド 型 デフォルト値 説明
prompt string、1〜8000 文字 — 必須。編集の場合は、何を変更するか、そして何を完全に維持しなければならないかを記述してください。
image_urls URL の配列 — image-to-image のみ、必須。1〜16 枚の JPEG、PNG、または WebP 画像で、各画像は最大 20 メガピクセル、30 MB 以下。公開ダウンロード可能な URL または data URI である必要があります。
aspect_ratio 列挙型 "auto" auto、1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9、27:16、16:27、9:8、8:9。
resolution 列挙型 "1K" 1K、2K、4K。これが価格を決定します。
background 列挙型 なし transparent、opaque、auto。transparent は 1K でのみ有効で、この場合はアルファチャンネル付き PNG が返されます。

編集の例 — 1 枚以上の参照画像を渡し、希望する変更だけを記述します：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "セラミック製カップの色だけをマットブラックに変更してください。大理石のカウンター、照明、カメラアングルはそのまま完全に維持してください。",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

この schema は厳格です（additionalProperties: false）。未知のフィールドは拒否されるため、他の画像モデルのパラメータ（size、strength、n など）を持ち込まないでください。

本番パターン

実際のバックエンドではポーリングではなくコールバックを使用します。 callback ブロックを追加するとポーリングループを省略できます：

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" はタスクが終端状態（success または fail）に達したとき、ちょうど 1 回だけ発火します。エンドポイントは素早く 2xx を返し、実際の処理（出力のダウンロード、自前のデータベースの更新）は非同期に実行してください。hiapi は迅速な確認が得られなかったコールバックを再試行します。

再試行を冪等にします。 クライアントのリクエストがタイムアウトした場合、タスクが作成されたかどうかは判断できません。作成リクエストに Idempotency-Key ヘッダー（最大 255 バイト）を付与し、再試行時に同じキーを再利用してください。同じアカウントとキーではタスクは 1 つだけ作成され、再試行は元の taskId を返します。これがないと、同じプロンプトを重複処理すると 2 回課金されます。

実際に遭遇する終端状態を処理します：

  • success — data.output[0].url を読み取り、速やかにダウンロードします（expireAt を遵守）。
  • fail — 再試行する前に data.error を確認して失敗理由を把握します。すべての失敗に対して盲目的に再試行しないでください。中にはプロンプトレベルの問題（ポリシー違反など）もあり、そのまま再試行しても失敗します。
  • 存在しないタスク id（誤記、期限切れ）をポーリングすると、HTTP 404 と {"code":404,"message":"task not found"} が返されます。

認証失敗はタスクレベルのエラーではなく、HTTP 401 です：

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

タスクの失敗と決めつける前に、エラーハンドリングでこれをチェックしてください。無効または取り消されたキーは、タスク作成段階にそもそも到達しません。

関連記事

よくある質問

gpt-image-2.5-sunburst は画像編集をサポートしますか、それともテキストからの画像生成のみですか？ 両方をサポートしており、2 つのモデル id で実現します。編集や合成には gpt-image-2.5-sunburst/image-to-image を image_urls（1〜16 枚の参照画像）と組み合わせて使用し、テキストのみからの生成には gpt-image-2.5-sunburst/text-to-image を使用します。

image_urls を省略するのではなく、空の配列を送信するとどうなりますか？ そうしないでください。image-to-image では image_urls は必須で、少なくとも 1 つの URL が必要です。純粋なテキスト生成には text-to-image モデル id を使用してください。

画像 1 枚の価格はいくらですか？ resolution によって異なります。1K は $0.05、2K は $0.08、4K は $0.12 で、text-to-image と image-to-image は同じです。プログラマーの日キャンペーン期間中（2026 年 11 月 9 日 00:00 UTC+8 まで）、すべての価格帯が 50% オフになります：$0.025、$0.04、$0.06。スケールアップする前に、モデルページで最新の価格を確認してください。

アスペクト比ではなく固定のピクセルサイズを指定できますか？ はい。aspect_ratio は 16:9 のような比率文字列に加えて、1024x1024、1536x1024、3840x2160 のようなリテラルなサイズも受け付けます。

タスクをポーリングすると 404 が返るのはなぜですか？ taskId の誤記か、ポーリングしているエンドポイント/リージョンにそのタスクが存在しないかのどちらかです。作成レスポンスから保存した id を慎重に確認してください。hiapi は通常のポーリングウィンドウ内でタスクレコードを黙って期限切れにすることはありません。

API キーなしでテストのために呼び出せますか？ いいえ。すべての /v1/tasks リクエストには Authorization: Bearer sk-<key> が必要です。匿名モードやブラウザのみのモードはありません。

タグAPI画像生成

関連記事

すべての記事を見る →

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む