hiapi API で flux-2/image-to-image を使う方法：curl、Python、および利用可能なリクエスト例

要点

• これは何か：hiapi 上で flux-2/image-to-image API を呼び出すための実践的な方法——タスクの作成、ステータスのポーリング、結果のダウンロード。
• エンドポイント：POST https://api.hiapi.ai/v1/tasks を使用し "model": "flux-2/image-to-image" を指定した後、GET /v1/tasks/<taskId> でタスクが終了状態になるまで確認します。
• 必須入力フィールド（全4つ）：prompt、image_urls（1〜8個の公開 URL——これが複数参照画像機能です）、aspect_ratio、resolution（1K または 2K）。
• スキーマは厳格です。strength や fidelity などのフィールドは存在せず、400 で拒否されます。忠実度は参照画像、プロンプト、resolution によって制御されるものであり、個別の調整つまみによるものではありません。

これから構築するもの、そして準備するもの

目標：flux-2 に1枚または複数の参照画像とテキストプロンプトを送り、ダウンロード可能な編集済み/再描画された画像を受け取る——curl または Python で、SDK は不要です。

前提条件：

1. hiapi API キー——hiapi コンソールで作成します。キーは sk-... の形式で、Authorization: Bearer リクエストヘッダーに設定します。
2. 参照画像として使用する公開アクセス可能な画像 URL が少なくとも1つ。API はサーバー側で image_urls を取得するため、localhost のリンクやプライベートストレージバケットの URL は使用できません——公開バケット、CDN、または署名付き URL を使用してください。
3. curl、または Python 3.8 以上と requests（pip install requests）。

リクエストスキーマ

flux-2/image-to-image は hiapi の統一タスクインターフェース上で動作します。input オブジェクトは次のフィールドのみを受け付けます：

フィールド	型	必須	説明
prompt	string	はい	変更または生成する内容。最低3文字。
image_urls	string[]	はい	1〜8個の公開画像 URL。2枚以上 = 複数参照画像：flux-2 はすべての参照画像間で人物の同一性、製品、スタイルの手がかりを融合します。
aspect_ratio	string	はい	1:1、4:3、3:4、16:9、9:16、3:2、2:3、または auto（参照画像に従う）のいずれか。
resolution	string	はい	1K または 2K。

その他のフィールドはすべて拒否されます。例えば、strength や fidelity フィールドを送信すると次のように返されます：

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

この点は覚えておく価値があります：flux-2 の画像から画像へのモードには、ノイズ除去強度の調整つまみがありません。出力が参照画像にどれだけ忠実か（「高忠実度」編集 vs. 緩い再描画）は、プロンプトの書き方に依存します——例えば 「製品とそのラベル、比率を参照画像と完全に一致させたまま、背景だけを置き換える」——さらに、細部が重要な作業には resolution: "2K" を使用します。

最小限の動作例：curl

ステップ1——タスクを作成：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

作成に成功すると、タスク ID が data.taskId に返されます。

ステップ2——完了までポーリング：

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status が終了状態でない限り、数秒ごとにポーリングを続けます。"status": "success" になると、画像 URL は data.output[0].url にあります。

ステップ3——結果をすぐにダウンロード：

curl -s -o result.jpg "OUTPUT_URL"

出力 URL には expireAt タイムスタンプが付いています——一時的なものです。タスク成功後すぐにバイトをダウンロードする（または自分のストレージにコピーする）べきです。本番環境でタスク出力を直接ホットリンクしないでください。

最小限の動作例：Python

requests のみを使用した完全なスクリプト——作成、ポーリング、ダウンロード：

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # 一時 URL——すぐに保存してください
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

ここでは2枚の画像の image_urls を使用していることに注意してください——これが複数参照画像の実際の使い方です。最大8枚の参照画像を受け付け、モデルはそれらの間で組み合わせを行います（人物 + 服装、製品 + 背景スタイル、キャラクター + ポーズ参照など）。

本番運用の実践ガイド

ポーリングの代わりにコールバックを使用する。スクリプト以外のあらゆるシナリオでは、タスク作成時にコールバックを登録し、hiapi から終了状態の結果をあなたのサービスにプッシュさせます：

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

"when": "final" を使用すると、タスクが終了状態になったときに1回だけ POST を受け取ります。経験則：ポーリングは CLI、バッチ処理、その他短命なシナリオに適しており、コールバックはユーザー向けアプリケーションに適しています。なぜなら、画像ごとにワーカーがポーリングループを保持するのはスケールしないからです。公開コールバックエンドポイントを公開できない場合は、ポーリングしてください——ただし、間隔を5秒以上にバックオフさせるようにしましょう。

リトライを安全にする。タスク作成を本来の副作用として扱います：結果に基づいて行動する前に、返された taskId を自分のジョブレコードに保存し、リトライ時には、盲目的に新しいタスクを作成するのではなく、保存されたタスクの状態を再確認します（作成が成功するたびに個別に課金されます）。ジョブランナーが2回起動する可能性がある場合は、まず自分のジョブ ID で重複排除してください。

実際に遭遇するエラーを処理する：

• 401 permission_denied——キーが間違っている、またはキーがそのモデルを使用する権限を持っていない。レスポンスボディは以下の通りです：

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  コンソールでキーを確認してください。よくある原因については、無効な API キーチェックリストで説明しています。

• 400 INVALID_REQUEST——スキーマ違反です。message はすべての違反フィールド（必須フィールドの欠落、誤った列挙値、未知の余分なフィールド）を一度に列挙するため、リトライごとに1つのフィールドだけを修正するのではなく、全体を読んでください。

• タスクの status: "fail"——タスクは受け付けられましたが、生成に失敗しました。エラーは data.error にあります。作成時ではなく、ポーリング/コールバックのパスで処理してください。

• 出力 URL の期限切れ——成功から数分後にダウンロードが 4xx を返す場合、待ちすぎたということです。expireAt を再確認し、常にすぐにダウンロードしてください。

関連記事

• flux-2/image-to-image モデルページ——パラメータと現在の価格
• flux-2/text-to-image モデルページ——同じシリーズ、参照画像不要
• flux-2 を EC 商品画像に活用——テキストから画像への側面に基づくエンドツーエンドのソリューション
• hiapi 上の FLUX 1.1 Pro——前世代オプションとの比較
• hiapi の料金——解像度別の1枚あたりのコスト

よくある質問

flux-2 の画像から画像へは、いくつの参照画像を渡せますか？ 1〜8枚で、公開 URL として image_urls に設定します。8枚を超えると検証に失敗します（maxItems: got N, want 8）。

strength や fidelity パラメータはありますか？ ありません。入力スキーマは prompt、image_urls、aspect_ratio、resolution のみを受け付け、未知のフィールドは 400 で拒否されます。忠実度はプロンプトの表現で制御し（何を変更してはいけないかを明確に指定する）、細部が重要な場合は 2K を使用してください。

対応している解像度とアスペクト比は？ resolution は 1K または 2K です。aspect_ratio は 1:1、4:3、3:4、16:9、9:16、3:2、2:3、または auto のいずれか——auto は参照画像に従い、編集時に通常望ましいものです。

URL の代わりに base64 画像を送信できますか？ いいえ——image_urls は URL を受け付け、API が取得できるよう公開アクセス可能である必要があります。まずストレージバケットまたは CDN にアップロードし、生成された URL を渡してください（署名付き URL は使用可能です）。

flux-2 の画像から画像へは1枚あたりいくらですか？ 価格は解像度によって異なります——現在の1枚あたりの料金については、flux-2/image-to-image モデルページと料金ページをご覧ください。

生成された画像 URL の有効期間はどのくらいですか？ 出力 URL は一時的で、expireAt フィールドを含みます。タスク成功後すぐに画像のバイトをダウンロードして自分で保存してください。

flux-2/image-to-image と flux-2/text-to-image の違いは何ですか？ 同じモデルシリーズですが、モードが異なります：テキストから画像はプロンプトのみに基づいて生成し、画像から画像は1〜8枚の参照画像を必要とし、それに基づいて編集または組み合わせを行います。入力スキーマが異なるため、リクエストボディは互換性がありません。