チュートリアル

flux-2-klein-9b API：curl と Python ガイド

Aug 25, 2026

モデル: flux-2-klein-9b

hiapi 上で flux-2-klein-9b を使って画像を1枚生成するには、POST /v1/tasks の呼び出しとポーリングが1回ずつあれば十分です。これはプラットフォーム上のすべてのモデルが使う非同期タスクパターンと完全に同じです。本ガイドは実際のリクエストとレスポンス（タスク作成、ポーリング、最終的な画像 URL）を記録したもので、以下のコードは示唆的なコードではなく、そのままコピーして実行できます。

必要なもの

hiapi API キー——コンソールで作成します。すべてのリクエストで Bearer トークンとして送信されます。
エンドポイントサフィックスを含む完全なモデル ID。 flux-2-klein-9b は flux-2-klein-9b/text-to-image 経由でのみアクセスできます——flux-2-klein-9b だけを指定すると 400 が返ります（後述）。

最小限の動作するリクエスト（curl）

タスクを作成します：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

レスポンス：

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

完了するまでタスクをポーリングします：

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

完了時のレスポンス：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url がその PNG です。テストでは、タスクは送信から success まで約 12 秒かかりました。expireAt に注意してください——この URL が継続的に利用できることに依存する機能を構築する前に、以下のストレージに関する注意事項を読んでください。

Python での同じ流れ

import time
import requests

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


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

flux-2-klein-9b が実際に検証するパラメータ

入力スキーマは非常に厳格です——記載されていないフィールドを1つでも送信すると、API はリクエストがキューに入る前にリクエスト全体を拒否します：

prompt（文字列、必須）——唯一の必須フィールドです。
aspect_ratio（文字列、任意）——値は 1:1、4:3、3:4、16:9、9:16 のいずれかです。それ以外の値は 400 を返し、value must be one of ... が付きます。
seed（整数、任意）——同じ prompt に対して同じ seed を渡すと、再現可能な結果が得られます。
output_format（文字列、任意）——値は jpeg、png、webp のいずれかです。

スキーマは以上です。size、quality、strength、n フィールドは存在せず、いずれかを送信すると失敗します：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'size' not allowed"}

flux-2-klein-9b はテキストから画像への生成のみをサポートします。image_urls も受け付けません——画像から画像への生成が必要な場合は、別の flux-2-klein-9b/image-to-image モデル ID を使用してください。こちらは異なる入力構造を受け付けます。

モデル ID にはエンドポイントサフィックスが必須

hiapi 上の一部のモデルはベア ID で解決できます（例：gpt-image-2）が、flux-2-klein-9b はその類ではありません。サフィックスを外すと、タスクは決して作成されません：

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

常に完全な flux-2-klein-9b/text-to-image 文字列を model として送信してください。

本番環境での注意事項

2種類の異なるエラー構造。 検証エラー（フィールド不足、不正な列挙値、未知のキー）はトップレベルの {"code":400,"error_code":"INVALID_REQUEST","message":"..."} 形式で返されます。認証/権限エラーは {"error":{"code":"permission_denied","message":"...","request_id":"..."}} で返されます——ネストされた error オブジェクトで、HTTP 401 です。エラー処理では両方の構造をチェックしてください。resp["code"] だけをチェックするコードは 401 のケースを見逃します。
permission_denied はリクエストではなくキーを指します。 prompt が存在し型も正しいのに 401 permission_denied を受け取る場合、その API キー自体でこのモデルが有効になっていません——JSON を何度も確認するのではなく、コンソールで確認してください。
出力ストレージは一時的です。 storage: "temp" であり、各出力には expireAt の unix タイムスタンプが付きます——取得した例では作成から約1週間後です。タスク成功後は直ちにファイルをダウンロードするか、独自のストレージにプッシュしてください。temp.hiapi.ai の URL を永続アドレスとして保存しないでください。
バッチタスクにはコールバックを使用してください。 画像1枚のポーリングは問題ありませんが、50枚のポーリングは50回の繰り返し往復になります。作成リクエストのトップレベルに callback: {"url": "...", "when": "final"} を設定すると、hiapi がタスクの実際の完了時に結果を一度だけプッシュします。現在 when は "final" のみをサポートしています。
再試行は taskId を取得する前に行い、取得後には行わないでください。 最初の POST /v1/tasks でネットワークエラーや 5xx が発生した場合は安全に再試行できます——この時点ではまだ何も作成されていません。一度 taskId を取得した後に同じ prompt を再送信すると、2枚目の無関係な画像が作成されます。この場合はポーリングするかコールバックを待つようにしてください。

よくある質問

flux-2-klein-9b を呼び出すと MODEL_UNAVAILABLE になるのはなぜですか？ モデル ID にはエンドポイントサフィックスが必要です。ベアの flux-2-klein-9b ではなく、flux-2-klein-9b/text-to-image を使用してください。

flux-2-klein-9b はどのアスペクト比をサポートしていますか？ 5種類です：1:1、4:3、3:4、16:9、9:16。それ以外の値は 400 を返し、これら5つの値を列挙した value must be one of メッセージが付きます。

出力の品質や解像度を制御できますか？ できません——スキーマは prompt、aspect_ratio、seed、output_format のみを受け付けます。size や quality パラメータはなく、いずれかを送信すると additional properties の 400 エラーが返ります。

flux-2-klein-9b で画像から画像への編集はできますか？ このモデル ID ではできません。flux-2-klein-9b/image-to-image を使用してください。こちらは独自の入力スキーマを持っています。

出力 URL の有効期間はどれくらいですか？ storage は "temp" で、各出力には expireAt の unix タイムスタンプが付き、実際には約1週間後です。タスク成功後は直ちにファイルをダウンロードするか再アップロードしてください——URL を永続アドレスとして扱わないでください。

他のモデルでは使えるキーがこのモデルで 401 になるのはなぜですか？ モデルへのアクセス権はキーごとに付与されます。401 かつ error_code: "permission_denied" が返る場合、その特定のキーに flux-2-klein-9b の権限がまだ付与されていないことを意味します——コンソールで有効化してください。リクエストボディのバグではありません。