チュートリアル

hiapi API で flux-2-klein-4b/text-to-image を使用する方法

Jul 30, 2026

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: hiapi API で flux-2-klein-4b/text-to-image を使用する方法 category: tutorial summary:

hiapi の統一された /v1/tasks エンドポイントを通じて flux-2-klein-4b/text-to-image を呼び出す、最も簡潔な curl と Python の例。
完全なパラメータ表：prompt、aspect_ratio の列挙値、seed — 厳格な schema は未知のフィールドを拒否します。
本番環境での注意点：callback.url とポーリングのトレードオフ、Idempotency-Key リクエストヘッダー、および 2 種類のエラーレスポンスの構造。 takeaways:
POST /v1/tasks でタスクを作成し、その後 GET /v1/tasks/{taskId} をポーリングするか、callback.url で結果を受け取ります。
aspect_ratio は 11 種類の名前付き比率をサポートします。このモデルには size や n フィールドはありません。
リトライ時に同じ Idempotency-Key リクエストヘッダーを付けると同じ taskId が返されます — タイムアウト時にも安全に再利用できます。
400 エラーは error_code を使用し、401 認証エラーはネストされた error.code を使用します — まず HTTP ステータスコードを確認してください。 meta_title: flux-2-klein-4b テキストtoイメージ API ガイド meta_description: 'curl と Python で flux-2-klein-4b/text-to-image を呼び出す：タスクの作成、ポーリングによる画像取得、そして本番環境でのコールバック、冪等性、エラーの処理。' keywords:
flux-2-klein-4b テキストtoイメージ api
flux-2-klein-4b api の例
hiapi 画像生成 api
flux api curl python tags:
api-guide
image-generation
flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

hiapi API で flux-2-klein-4b/text-to-image を使用する方法

何を構築するか

スクリプト：flux-2-klein-4b/text-to-image にプロンプトを送信し、画像の生成を待ってから画像をダウンロードします — さらに、無人実行の前に知っておくべき本番環境の詳細（コールバック、冪等性、エラー構造）も含みます。

前提条件：hiapi コンソールから API key を取得してください。以下の各リクエストは Authorization: Bearer sk-<your-api-key> で認証します。

最小の動作例

hiapi の生成モデルは統一された非同期エンドポイントの背後で動作します：POST /v1/tasks がタスクを作成し、即座に taskId を返します。その後 GET /v1/tasks/{taskId} をポーリングし、終了状態に達するまで待ちます。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

返される結果：

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

同じタスクをポーリングし、data.status が handling から success に変わるまで待ちます（その間、短時間 archiving を経由します）：

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

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

data.output[0].url が生成された画像です。これは一時リンクであり — テストでは生成から約 7 日後に期限切れになります — そのため、このアドレスに直接リンクするのではなく、画像のバイトデータをダウンロードして自分で保存してください。

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"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-4b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.jpg", "wb").write(image_bytes)

重要なパラメータ

flux-2-klein-4b/text-to-image は厳格な入力 schema を採用しています — 認識しないフィールド（size、n、negative_prompt、あるいは他の hiapi 画像モデルが受け入れるあらゆるフィールド）を送信すると、そのまま拒否されます。したがって、モデルページを先に確認せずに、モデル間でパラメータをコピーしないでください。

フィールド	必須	説明
`prompt`	はい	画像を説明する文字列。
`aspect_ratio`	いいえ	次のいずれかの値：`1:1`、`16:9`、`9:16`、`3:2`、`2:3`、`4:3`、`3:4`、`5:4`、`4:5`、`21:9`、`9:21`。省略時は `1:1` がデフォルトです。
`seed`	いいえ	整数。同じ seed を再利用すると、複数回の呼び出しで結果を再現できます。

完全なパラメータリファレンスはモデルページを参照してください。現在の 1 枚あたりの価格は料金ページを参照してください — 従量課金の価格は変動するため、数値をハードコードするのではなく、そちらを基準にしてください。

本番環境に関する注意事項

ポーリングの代わりにコールバックを使用する。 簡単なスクリプト以外では、ポーリングループを省略し、タスク作成のリクエストボディに callback.url（および "when": "final"）を追加してください — タスク完了後、hiapi が結果をあなたのエンドポイントに POST します。そのペイロード構造は GET /v1/tasks/{taskId} が返すものと完全に同じです。コールバックフィールドと署名検証の詳細については、タスクの作成を参照してください。

{
  "model": "flux-2-klein-4b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

冪等性。 POST /v1/tasks の呼び出しで Idempotency-Key リクエストヘッダーを設定します（最大 255 バイト）。同じアカウントで同じ key を使用して同じリクエストをリトライしても、2 つ目のタスクは作成されません — 元の taskId が返されます。これにより、あなた側でタイムアウトしたリクエストを重複課金なしで安全にリトライできます。

エラー処理。 実際には 2 種類の異なる失敗構造が発生するため、両方を確認してください：

誤った input（prompt の欠落、aspect_ratio が範囲外、サポートされていないフィールド）は HTTP 400 を返し、レスポンスボディは {"error_code": "INVALID_REQUEST", "message": "..."} です。
無効または未認可の API key は HTTP 401 を返し、レスポンス構造が異なります：{"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}。

まず HTTP ステータスコードで分岐してから、実際に存在するエラーフィールドを読み取ってください — すべての失敗が同じレスポンス構造を使用すると仮定しないでください。

よくある質問

flux-2-klein-4b/text-to-image は image-to-image をサポートしていますか？ 直接はサポートしていません — それは別のモデル flux-2-klein-4b/image-to-image であり、独自の入力 schema を持っています。

flux-2-klein-4b と flux-2-klein-9b の違いは何ですか？ どちらも同じ FLUX.2 [klein] シリーズのテキストtoイメージエンドポイントです。9b は両者の中でより大きな方です。切り替える前に 9b モデルページで現在の価格とパラメータを確認してください。

1 回の呼び出しで複数の画像をリクエストできますか？ いいえ — schema は n や数量フィールドを受け入れません。画像ごとに 1 回のリクエストを送信する必要があります。

返される画像 URL の有効期限はどのくらいですか？ output[0].url は独自の expireAt タイムスタンプを持つ一時リンクです。短期間有効（テストでは約 1 週間）とみなし、タスク成功後すぐに画像のバイトデータをダウンロードしてください。URL を保存しないでください。

なぜ 401 permission_denied エラーが返されるのですか？ key が欠落している、無効である、またはそのモデルにアクセスする権限がありません。Authorization: Bearer sk-... を送信していること、およびプレースホルダーではなくコンソールから取得した key を使用していることを確認してください。

この API を使用するには独自のサーバーを実行する必要がありますか？ コールバックが必要な場合のみです。スクリプト、cron ジョブ、サーバーレス関数から GET /v1/tasks/{taskId} をポーリングすることは、低トラフィックのシナリオではまったく問題ありません。生成規模が大きくなったら、callback.url に切り替えてください。