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

FLUX.2 [klein] 4B は Black Forest Labs がリリースしたコンパクトで高速な画像編集モデルです。参照画像と自然言語の指示を渡すと、最大 4 MP の編集済み画像を返します。hiapi 上では、他のすべてのモデルと同様に同じ Unified Async API を通じて動作します——POST /v1/tasks でタスクを作成し、ポーリングまたはコールバックで結果を取得します。本ガイドでは、正確なリクエスト構造、動作する curl/Python の例、そして本番環境への組み込み方法を解説します。

必要なもの

• hiapi API キー。dashboard から取得できます——キーは sk-... の形式で、Authorization: Bearer リクエストヘッダーに含めます。
• 公開アクセス可能な参照画像の URL（jpeg、png、webp——svg は非対応）。4 MP を超える画像は自動的に 4 MP に縮小されます。
• flux-2-klein-4b/image-to-image の現在の料金は解像度別の段階制（0.25 MP から 4 MP）です——リアルタイムの価格は hiapi pricing で確認してください。ここにハードコードしないでください。

最小限の動作例

モデル ID は flux-2-klein-4b/image-to-image です——必ずこの通りに（スラッシュを含めて）model の値として使用してください（URL パスに入れないでください）。すべての hiapi モデルは同じエンドポイントを共有しており、input オブジェクトのフィールドのみがモデルごとに異なります。

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/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

このリクエストは即座に taskId を返します——生成は非同期で行われます：

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

結果をポーリングして取得します：

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

status が "success" になると、編集済み画像は data.output[0].url にあります。この URL は一時的なもの（expireAt 付き）なので、すぐにダウンロードするか再ホスティングしてください——このホットリンクを直接保存しないでください。

同じ処理を Python で実装します：

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.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_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

リクエストパラメータ

flux-2-klein-4b/image-to-image は厳格な入力スキーマを受け付けます——ここに記載されていない追加フィールドは拒否され、400 が返されます：

フィールド	必須かどうか	説明
prompt	はい	適用する編集の自然言語による説明。
image_urls	はい	ちょうど 1 つの参照画像 URL を含む配列。複数渡すと maxItems: got N, want 1 が返されます。
resolution	いいえ	次のいずれか：0.25 MP、0.5 MP、1 MP（デフォルト）、2 MP、4 MP。0.25/0.5 MP は低コストの下書きに、2/4 MP は最終出力に使用します。
aspect_ratio	いいえ	次のいずれか：match_input_image（デフォルト）、1:1、16:9、9:16、3:2、2:3、4:3、3:4、5:4、4:5、21:9、9:21。
seed	いいえ	整数。それ以外が完全に同一のリクエスト間で再現可能な出力を実現するために使用します。
output_format	いいえ	jpg（デフォルト）、png、または webp。
output_quality	いいえ	整数。jpg/webp の圧縮品質（デフォルト 95）。

このモデルには size や n フィールドはありません——これらは他のプロバイダーの慣習であり、このスキーマでは認識されません。各 hiapi モデルは独自のフィールドセットを持つため、他のモデル向けに構築したリクエストを移植する前にモデルリファレンスページを確認してください。

本番環境での注意点

ポーリングよりもコールバックを優先してください。 トップレベルの callback オブジェクトを追加すると、hiapi はループ内でポーリングさせるのではなく、あなたのサービスに通知します：

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when は "final" のみを受け付けます——タスクが終端状態（success または fail）に達したときに一度だけ通知を送信するもので、進捗ストリームではありません。コールバックはウェイクアップ信号として扱ってください：受信後も、権威ある状態を読み取るために GET /v1/tasks/<taskId> を実行すべきであり、重複配信に備えてハンドラを taskId に対して冪等に保つ必要があります。

冪等性。 create_task が返した直後に taskId を永続化してから、ポーリングやコールバック待機を開始してください。待機中にプロセスがクラッシュした場合、再起動後はタスクを再作成するのではなく GET /v1/tasks/<taskId> で復旧してください——タスク作成は課金イベントであり、GET は無料で繰り返し実行できます。

エラーハンドリング。 無効または未認可のキーは HTTP 401 と構造化されたレスポンスボディを返します：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

request_id を記録してください——サポートチームはこれを使って正確な呼び出しを特定できます。形式が不正な input（prompt/image_urls の欠落、サポートされていない aspect_ratio の値、または認識できない追加フィールド）は 400 を返し、error_code: "INVALID_REQUEST" とともにメッセージで問題のあるフィールドを指摘します。そのまま再試行するのではなく、リクエストボディを修正してください。

関連情報

• FLUX.2 [klein] 4B 画像から画像へのモデルリファレンス——完全なパラメータドキュメントとサンプルリクエストボディ。
• FLUX.2 [klein] 4B テキストから画像へのモデルリファレンス——参照画像が不要な、対応するテキストから画像へのバリエーション。
• hiapi pricing——現在の解像度別段階制の画像あたりのコスト。
• Unified Async API の概要——プラットフォーム上のすべてのモデルが共有する POST /v1/tasks / GET /v1/tasks/:id 契約。

よくある質問

image_urls はどの画像形式を受け付けますか？ jpeg、png、または webp です。svg は非対応です。4 MP より大きい画像は編集前に自動的に 4 MP に縮小されます。

複数の参照画像を渡せますか？ いいえ——このモデルの image_urls は要素数がちょうど 1 つに制限されています。それ以上渡すと 400（maxItems: got N, want 1）が返されます。

なぜリクエストが "additional properties ... not allowed" と拒否されるのですか？ このスキーマは厳格です：上記のパラメータ表にないフィールド（例えば他のプロバイダーの size、n、strength などの慣習）はすべて 400 を引き起こします。正確に受け付けられるフィールドセットについてはモデルリファレンスを確認してください。

元の画像のアスペクト比を保つにはどうすればよいですか？ aspect_ratio を match_input_image に設定してください——このフィールドを完全に省略した場合もこれがデフォルト値です。

flux-2-klein-4b/image-to-image と 9B バリエーションの違いは何ですか？ 両者は同じリクエストスキーマ（prompt、image_urls、resolution、aspect_ratio、seed、output_format、output_quality）を共有しています。9B は速度とコストをいくらか犠牲にして、より強いリアリズム、テキストレンダリング、ディテールを得ます——素早く低コストで反復する場合は 4B を、編集が繊細なディテールにおいて堅牢である必要がある場合は 9B を使用してください。

コールバック URL は必要ですか、それともポーリングで十分ですか？ ローカル開発、低ボリュームのタスク、またはコールバック配信が漏れた場合のフォールバックとしては、GET /v1/tasks/:id によるポーリングで問題ありません。本番トラフィックでは、コールバックによってリクエストごとにポーリングループを回すオーバーヘッドを回避できます。