チュートリアル

hiapi API で gpt-image-2.5-flare を使用する方法

Sep 10, 2026

gpt-image-2.5-flare は hiapi 上の単一モデルであり、同じ統一エンドポイントを通じてテキストからの画像生成と画像編集の両方を処理します——「生成」と「編集」で別々のモデル ID を使い分ける必要はありません。本ガイドでは、hiapi の非同期タスク API を使って数分でゼロから実用的な画像を生成する方法を、完全な Node.js サンプルと、本番運用前に必要となる本番レベルのパターン（コールバック、冪等性、リトライ）とともに解説します。

準備するもの

hiapi API キー。登録してコンソールから取得してください——キーは sk-... の形式で、Authorization: Bearer リクエストヘッダーに含めます。
任意の HTTP クライアント。以下のサンプルは Node.js 18+（組み込みの fetch）を使用していますが、同じ 3 回の呼び出しは curl、Python、または JSON の POST リクエストを送信できるあらゆるツールでも実行できます。

hiapi は同じ非同期エンドポイント群を通じて gpt-image-2.5-flare を公開しています。タスクを送信してから結果をポーリングするか、タスク完了時に webhook コールバックを受信します。同期的に「レスポンスボディ内で画像を待つ」呼び出しは存在しません——生成には数秒かかるため、API は最初からタスクベースになっています。

最小限の動作サンプル（Node.js）

以下のコードはタスクを作成し、完了するまでポーリングを行い、生成された画像の URL を出力します。

const API_KEY = process.env.HIAPI_API_KEY; // sk-...
const BASE = "https://api.hiapi.ai/v1/tasks";

async function createTask(prompt) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      input: {
        prompt,
        aspect_ratio: "16:9",
        quality: "high",
      },
    }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`create task failed (${res.status}): ${JSON.stringify(err)}`);
  }
  const { data } = await res.json();
  return data.taskId; // e.g. "tk-hiapi-..."
}

async function waitForTask(taskId, { timeoutMs = 120_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/${taskId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    const { data: task } = await res.json();
    if (task.status === "success") return task;
    if (task.status === "fail") {
      throw new Error(`task failed: ${task.error?.code} ${task.error?.message}`);
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

const taskId = await createTask("a minimalist poster of a lighthouse at dawn, flat color");
const task = await waitForTask(taskId);
console.log(task.output[0].url); // download this — it expires, so save it promptly

HIAPI_API_KEY=sk-... node generate.js で実行します。レスポンスの data.output 配列は status が "success" の場合にのみ現れます。各エントリには一時的な url（expireAt 付き）があるため、リンクを保存するのではなく、すぐにダウンロードするか再アップロードしてください。

ゼロから生成するのではなく既存の画像を編集する場合は、input.image_urls（公開アクセス可能な URL の配列、1〜16 枚の画像）を追加し、各画像に対して何をするかを prompt で記述してください——同じモデル、同じエンドポイントで、別の「編集」モデル ID は不要です：

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: {
    prompt: "replace the background with a studio gradient, keep the subject unchanged",
    image_urls: ["https://example.com/product-photo.jpg"],
  },
}),

その他の有用な input フィールド：background（auto / transparent / opaque、デフォルトは auto）と output_format（png / jpeg / webp、デフォルトは webp）。このモデルには resolution フィールドはありません——サイズは完全に aspect_ratio で制御します（比率ではなく正確なピクセルサイズが必要な場合は、1536x1024 のような明示的なピクセルサイズも受け付けます）。

本番レベルのパターン

本番環境ではポーリングの代わりにコールバックを使用しましょう。ポーリングはスクリプトには適していますが、実際のバックエンドでは、定期的に GET /v1/tasks/<id> を繰り返しリクエストするのではなく、webhook を登録して、タスクが完了した瞬間に hiapi から通知を受け取るようにしてください：

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: { prompt: "..." },
  callback: {
    url: "https://yourapp.com/webhooks/hiapi",
    when: "final", // the only supported value — fires once, on success or fail
  },
}),

webhook ハンドラーは、GET /v1/tasks/<id> をポーリングしたときと同じタスクオブジェクトを受け取ります——status を確認し、success と fail で分岐して処理してください。

リトライを冪等にしましょう。タスク実行基盤が失敗した HTTP 呼び出し（タイムアウト、5xx、ネットワークの一時的な乱れ）を不注意にリトライすると、同じ生成タスクを二重に送信し、両方に対して課金されてしまう可能性があります。安定した Idempotency-Key リクエストヘッダー（最大 255 バイト、通常は自社のタスク/リクエスト ID）を渡してください——同じ key を使ったリトライリクエストは、新しいタスクを作成するのではなく元のタスクを返します：

headers: {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": jobId, // reuse the same value across retries of the same logical request
},

特定の失敗モードを処理しましょう。以下のステータスコードは、すべてを「リトライ」として扱うのではなく、明示的に分岐して処理する必要があります：

ステータスコード	意味	対処方法
`401` かつ `error.code: "permission_denied"`	API キーが誤っているか欠落している	リトライしない——`Authorization` ヘッダーを確認する
`402`	残高不足	リトライしない——先にチャージする
`400`	リクエストボディが不正（フィールドの誤り、型の誤り）	むやみにリトライしない——リクエストボディを修正する
`503`	一時的に利用不可	バックオフして安全にリトライできる
タスク `status: "fail"`	タスクが受理された後に失敗（例：`image_urls` にアクセスできない）	`error.code` / `error.message` を確認し、無限ループにしない

401 エラーのレスポンスボディは以下のとおりです——すべての hiapi モデルで同じ形状なので、共有エラーハンドラーで一度チェックしておく価値があります：

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

リファレンス

gpt-image-2.5-flare モデルページ——リアルタイムの料金と、コードに組み込む前に prompt をオンラインで試せる playground があります。
非同期タスク API ドキュメント：タスクの作成とタスクステータスの取得——このモデルに限らずすべてのモデルの完全なフィールドリファレンスです。
認証ドキュメント——API キーと Authorization ヘッダーがすべての hiapi エンドポイントでどのように機能するか。
gpt-image-2 から既存コードを移行する必要がある場合、または Sunburst 専用の編集チュートリアルが必要な場合は、GPT Image 2.5 API ガイドで移行パスを参照してください。
料金——現在の品質ティア別の 1 画像あたりのコスト（変動するためここには転記しません）。

よくある質問

gpt-image-2.5-flare は 1 つのモデルですか、それとも 2 つ（生成 + 編集）ですか？1 つです。生成するか編集するかは、input.image_urls を含めるかどうかだけで決まります——別のモデル ID に切り替える必要はありません。

なぜレスポンスにすぐ画像が現れないのですか？hiapi の画像モデルはすべて非同期です——POST /v1/tasks は taskId のみを返します。status が success になるまで GET /v1/tasks/<id> をポーリングするか、callback を登録して実際の output 配列を取得する必要があります。

タスクにはどのくらい時間がかかりますか？通常は一桁秒ですが、負荷が高いときは時々長くなることがあります。常に即座に完了すると仮定せず、余裕のあるポーリングタイムアウト（60〜120 秒）を使用してください。

編集時に複数の参照画像を渡せますか？はい、image_urls は最大 16 枚の画像を受け付けます——配列の順序が重要なので、prompt で各画像の役割を説明してください（例：「1 枚目の画像のポーズに、2 枚目の画像の服装を組み合わせる」）。

タスク完了時にコールバック URL にアクセスできない場合はどうなりますか？hiapi はタスクが最終状態に達したときに一度だけ呼び出します（when: "final"）。エンドポイントにアクセスできない場合、通知は届きません——見逃せないあらゆるケースでは、フォールバックとしてポーリングを使用するか、記録したタスク ID を使って定期的に GET /v1/tasks/<id> と突き合わせてください。

出力 URL を自分で保存する必要がありますか？はい——output[0] の url は一時的なものであり、期限切れになります。タスク成功後すぐにダウンロードするか、自社のストレージに再アップロードしてください。