HiAPI
Ja
ブログ

チュートリアル

GPT Image 2.5 Sunburst テキスト画像生成 API：動作する curl と Python ガイド

Sep 12, 2026
GPT Image 2.5 Sunburst テキスト画像生成 API：動作する curl と Python ガイド

hiapi API 経由で gpt-image-2.5-sunburst/text-to-image を使って画像を生成したい場合、本ガイドでは curl と Python のそれぞれで、タスクの作成から最終的な画像 URL のダウンロードまで、完全かつ動作するリクエストを順を追って説明します。ここに示すすべてのリクエスト/レスポンスは、公開前に対象の本番 API に対して実際に実行したものです。

前提条件

  • hiapi アカウントと API キー（sk-...）をお持ちであること。hiapi コンソールで取得できます。
  • curl、または Python の例に沿って進める場合は Python 3.8 以上。
  • 少なくとも出力画像 1 枚分の予算。gpt-image-2.5-sunburst/text-to-image は出力解像度に応じて課金されます。料金は変動する可能性があるため、本番環境で実行する前に現在の料金をご確認ください。

すべてのリクエストで標準のリクエストヘッダーを使用します：

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

最小限の動作例

hiapi の画像モデルはすべて同じ非同期タスク API 上で動作します。POST でタスクを作成し、終了状態に達するまでポーリング（または webhook コールバックを受信）してから、output[0].url から画像 URL を読み取ります。

1. タスクの作成（curl）

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "大理石のカウンター上のセラミック製コーヒードリッパーのミニマルな製品写真、柔らかな朝の光、35mm レンズ風",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

呼び出しが成功するとタスク ID だけが返されます。生成は非同期で行われます：

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

2. 結果のポーリング

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

数秒おきにポーリングを続け、data.status が終了状態の値になるまで待ちます。成功時のレスポンスは次のとおりです（taskId/URL は読みやすさのために短縮しています）：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

画像は data.output[0].url から取得します。この URL は期限切れになります（expireAt、Unix タイムスタンプを参照）。タスク成功後すぐにバイトをダウンロードして自分で保存し、永続リンクとして扱わないでください。

3. Python のエンドツーエンド例

import time
import requests

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


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("大理石のカウンター上のセラミック製コーヒードリッパーのミニマルな製品写真")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

input が実際に受け付けるフィールド

gpt-image-2.5-sunburst/text-to-image の schema は小さく厳格です。受け付けるのは以下のフィールドのみで、それ以外のフィールド（quality、size、n、output_format、style、seed）はすべて 400 で拒否されます：

フィールド 必須 値
prompt はい 任意の文字列
resolution いいえ（デフォルトは 1K） 1K、2K、4K
aspect_ratio いいえ 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
background いいえ transparent、opaque、auto

これは裸の gpt-image-2.5-sunburst モデルの schema とは異なります。後者は quality の段階（low/medium/high/xhigh/max/auto）を受け付け、image_urls による画像から画像への編集にも対応しています。両者の料金も異なるため、具体的な数字に依存する前に /en/pricing でご確認ください。料金は変動する可能性があります。

本番環境でのパターン

ポーリングの代わりに Webhook コールバックを使用する

簡単なスクリプト以外のあらゆる場面では、ポーリングをやめて、タスク完了時に hiapi からコールバックを受け取るようにします。同じ POST /v1/tasks リクエストにトップレベルの callback オブジェクトを追加します：

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

when: "final" は現時点で唯一サポートされる値です。タスクが終了状態（success または fail）になると、エンドポイントが 1 回呼び出され、ペイロードの構造はポーリングで得られる結果と同じです。

ポーリングとコールバックの比較：ポーリングはスクリプトや notebook では正しく実装しやすく、公開エンドポイントも不要ですが、完了を知るまでにリクエストを無駄にし、遅延（平均してポーリング間隔分）が増えます。サーバー側の統合や同時実行数の多いあらゆる場面ではコールバックが適しています。ポーリングループを完全に回避でき、タスクが完了した時点で通知を受け取れます。

リトライ時の冪等性

タスク API は model/input/callback と並ぶトップレベルの idempotency_key 文字列を受け付けます。クライアントがタイムアウト後に POST をリトライする可能性がある場合（リクエストを送信したがレスポンスを一度も受け取らなかった場合など）、安定したキーを付けておけば、元のリクエストが実際に届いたかどうかを推測するのではなく、照合するための明確なシグナルが得られます。

エラーの処理

無効または期限切れの API キーは HTTP 401 と構造化されたエラーボディを返します：

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

誤った input 値（誤った列挙メンバー、prompt の欠落、未サポートのフィールド）はタスク作成前に HTTP 400 を返すため、課金されることはありません：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

この 2 つのケースを明示的に処理してください。一時的なネットワーク/5xx エラーはリトライしますが、400 はリクエストボディを修正すべきシグナルとして扱い、盲目的にリトライしないでください。

関連リソース

よくある質問

resolution を指定する必要はありますか？ いいえ——省略するとデフォルトで 1K になります。2K や 4K の出力が必要な場合は、解像度が上がるほど価格も上がるため、明示的に設定してください。

他の GPT Image モデルのドキュメントのように quality を渡せますか？ このルートではできません。gpt-image-2.5-sunburst/text-to-image は quality を完全に拒否します。このパラメーターは裸の gpt-image-2.5-sunburst モデル ID にのみ存在し、後者は schema と料金が異なります。

なぜリクエストは画像ではなくタスク ID を返すのですか？ hiapi 上のすべての画像モデルは同じ非同期タスク API（POST /v1/tasks → ポーリングまたはコールバック → output[0].url）を通じて動作し、基盤モデルが実際にどれほど高速であっても変わりません。このパターンで一度統合を構築すれば、その後どのモデルに切り替えても同じ方法で動作します。

出力 URL を期限内にダウンロードしなかった場合はどうなりますか？ 期限切れになります。タスクレスポンスの expireAt フィールドは、一時 URL が機能しなくなる Unix タイムスタンプです。status が success になったらすぐに自分でバイトをダウンロードして保存してください。

このモデルで画像から画像への編集はできますか？ /text-to-image ルートではできません。画像編集には裸の gpt-image-2.5-sunburst モデル ID を使用し、image_urls 入力フィールドを渡してください。正確な schema についてはモデルページをご覧ください。

ご自分で試す準備はできましたか？ hiapi コンソールで API キーを取得し、上記の Python 例のプロンプトを置き換えるだけです。

タグAPIチュートリアルテキストから画像生成

関連記事

すべての記事を見る →

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

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

APIドキュメントを読む