チュートリアル

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

Sep 12, 2026

gpt-image-2.5-flare@pro は、hiapi の統合タスク API で提供される画像モデルの 1 つです。本ガイドでは、まず curl と Python で最小限の実行可能なリクエストを実演し、その後、本番環境に必要なパラメータとモード（コールバック、冪等性、エラーハンドリング）を紹介します。

準備するもの

hiapi API キー。これは hiapi コンソールから取得できます——どのキーも sk- で始まります。
ベース URL として https://api.hiapi.ai。すべてのリクエストには Authorization: Bearer sk-<your-key> ヘッダーが必要です。

hiapi 上の画像生成（および他のすべての非同期モデル——動画、TTS、音楽）は、同じエンドポイント POST /v1/tasks を通じて実行されます。まずタスクを作成し、その後 GET /v1/tasks/:id をポーリングするか、タスク完了時にコールバックを受け取ることができます。完全なリファレンスはこちら：統合非同期 API。

最小限の実行可能な例

curl

タスクを作成：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

ここで返されるのは画像ではなくタスク ID です——画像生成は非同期です：

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

結果をポーリング：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status は queued → handling → archiving → success（または fail）の順に変化します。ステータスが success のとき、画像は data.output[0].url にあります：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt は Unix タイムスタンプです——期限切れになる前にファイルをダウンロードするか再ホストしてください。期限切れ後、その URL は機能しなくなります。

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

唯一の依存関係は pip install requests でインストールし、HIAPI_API_KEY をエクスポートしてから実行するだけです。

主要なパラメータ

gpt-image-2.5-flare は 2 つのルートを提供します：デフォルトルート（モデル ID gpt-image-2.5-flare を直接使用）と pro ルート（上記のすべての例のように @pro を追加）。明示的な @default サフィックスは存在しません——それを渡すと MODEL_UNAVAILABLE が返されます。

input は以下のフィールドを受け付けます：

prompt（文字列、必須）——唯一の必須フィールドです。
aspect_ratio——1:1、3:2、2:3、4:3、3:4、16:9、9:16、auto、または 1536x1024、2048x2048、3840x2160 のような明示的なピクセルサイズ。
quality——low、medium、high、xhigh、max または auto。
output_format——png、jpeg または webp。
background——auto、transparent または opaque。output_format: png または webp と組み合わせて transparent を使用すると、切り抜き素材が得られます。

このスキーマは厳格です——未知のフィールド（size、n、またはリストにない任意のフィールド）は黙って無視されるのではなく、400 INVALID_REQUEST と additional properties '<field>' not allowed を返します。空白のプロンプトから生成するのではなく既存の画像を編集する必要がある場合、hiapi では別のモデル ID として提供しています——image-to-image バリアントについてはモデルページをご覧ください。

本番環境のパターン

ポーリングではなくコールバックを使用する。 作成リクエストに callback オブジェクトを追加します：

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" は現在唯一サポートされている値です——タスクが success または fail に達すると、hiapi はあなたの URL に 1 回 POST リクエストを送信します。コールバック本体は GET /v1/tasks/:id が返す data フィールドとまったく同じです。

Idempotency-Key ヘッダーを送信する。 こちら側でリクエストがタイムアウトしてリトライした場合、冪等キーは hiapi が同じリクエストに対して 2 つ目のタスクを作成（および課金）するのを防ぎます。

エラーを明示的に処理する。 無効または取り消されたキーは HTTP 401 を返します：

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

形式が不正な input は HTTP 400 を返し、error_code: "INVALID_REQUEST" と問題のあるフィールドを示す message が付きます——リトライする前にこれを確認してください。同じリクエストボディでリトライすると 400 が再び発生するだけです。

gpt-image-2.5-flare@pro の料金（解像度と品質ティアに基づき、成功した生成画像に対して課金）については料金ページをご覧ください。

よくある質問

デフォルトルートと @pro の違いは何ですか？ これらは同じモデルシリーズの 2 つの独立したルートであり、送信するモデル ID（gpt-image-2.5-flare と gpt-image-2.5-flare@pro）によって選択されます。選択する前にモデルページと料金を確認し、現在のコストと機能の違いを把握してください。

透明な PNG を生成できますか？ はい——"background": "transparent" を設定し、"output_format": "png"（または "webp"）と組み合わせてください。

なぜ additional properties 'size' not allowed が返されるのですか？ スキーマは厳格です。size フィールドではなく、aspect_ratio（1024x1024 のような明示的なピクセルサイズも受け付けます）を使用してください。

出力 URL の有効期間はどのくらいですか？ output[0] オブジェクトの expireAt Unix タイムスタンプまでです。それまでにダウンロードするか、自分のストレージにコピーしてください——hiapi はその後そのファイルを提供し続けません。

コールバックを設定してもポーリングは必要ですか？ いいえ、ただしポーリングは引き続き可能です——コールバックが設定されているかどうかに関係なく、GET /v1/tasks/:id は通常どおり使用できます。コールバックエンドポイントが 1 回の配信を逃した場合、これを使って手動で再確認できます。

リクエストに input_urls と誤った prompt の両方が含まれている場合はどうなりますか？ 検証はタスク作成前にリクエストボディ全体に対して実行されます——無効なフィールド（形式が不正なメディア配列を含む）があると 400 が返され、タスクは作成されません（課金もされません）。