チュートリアル

FLUX.1 Fill Pro API の使い方：curl と Python によるマスクインペインティング

Oct 24, 2026

flux-1-fill-pro は hiapi のマスクベースのインペインティングモデルです。元画像、白黒マスク、プロンプトを送信すると、白い領域だけが再描画されます。本ガイドでは、実際に動作する curl と Python のリクエスト、非同期フロー、そして実際の1回の実行でマスクの境界と出力サイズに関して確認された結果を紹介します。API key は dashboard から取得する必要があります。

リクエスト構造

このモデルは統合タスク API 上で動作します。POST https://api.hiapi.ai/v1/tasks でタスクを作成し、GET /v1/tasks/<taskId> をポーリングして、data.output[0].url を読み取ります。以下の入力はモデルページとAPI ドキュメントに基づいています：

フィールド	型	説明
`input.image`	URL、必須	元画像。JPEG、PNG、GIF または WebP。
`input.mask`	URL、必須	黒は元画像を保持し、白は再描画されます。元画像とサイズが一致している必要があります。
`input.prompt`	string、必須	白い領域内の新しい内容を記述します。最大 4,000 文字。
`input.steps`	int、15–50	デフォルトは 50。
`input.guidance`	number、1.5–100	デフォルトは 60。
`input.seed`	int	同じ入力で seed を固定すると一貫した結果が得られます。
`input.output_format`	`jpg` \| `png`	デフォルトは `jpg`。
`input.prompt_upsampling`	bool	デフォルトは `false`。オフのままにすると、あなたの正確な表現を保持できます。

image と mask はどちらも URL であり、base64 やファイルアップロードではありません。API が http(s) で取得できる場所にホストしてください。

最小限の curl リクエスト

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418739459-82bb18075f29c864-mask.png",
      "prompt": "朝霧の中にぼんやりと浮かぶ山と湖の油彩風景画の大作。細い黒い額縁に入れられ、壁に平らに掛けられている。ソファ、床、照明はそのまま維持する。",
      "steps": 30,
      "guidance": 60,
      "seed": 42,
      "output_format": "png"
    }
  }'

レスポンスは {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"} です。data.status が success または fail になるまで、この ID をポーリングします。

Python：作成、ポーリング、ダウンロード

import os, time, requests

API = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def inpaint(image_url, mask_url, prompt, **opts):
    body = {"model": "flux-1-fill-pro",
            "input": {"image": image_url, "mask": mask_url, "prompt": prompt, **opts}}
    r = requests.post(f"{API}/v1/tasks", headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:
        try:
            d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=20).json()["data"]
        except requests.RequestException:
            time.sleep(5)          # transient network error: poll the same taskId again
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error", d))
        time.sleep(5)

url = inpaint(
    "https://example.com/room.jpg",
    "https://example.com/room-mask.png",
    "額縁に入った風景画、細い黒い額縁。部屋はそのまま維持する。",
    steps=30, seed=42, output_format="png",
)
open("out.png", "wb").write(requests.get(url, timeout=60).content)

結果はすぐにダウンロードしてください。出力 URL には expireAt が付与され、ファイルは一時保存されるため、そのリンクを永続的なアドレスとして保存しないでください。

本番環境での注意点

ポーリングまたはコールバック。バッチ処理の場合は、タスク body に "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} を追加し、タスク ID で通知の重複を排除します。ポーリングはフォールバックとして保持してください。
リトライするのはポーリングであり、作成ではありません。新たな POST は新しいタスクを作成し、課金されます。ポーリングリクエストがエラーになった場合は、同じ taskId を再度ポーリングしてください。
マスクは元画像と一致させる。マスクは元画像と寸法が完全に一致している必要があるため、スクリーンショットを拡縮するのではなく、同じファイルから生成してください（ポリゴンツール、セグメンテーション出力など）。
パラメータ調整時は seed を固定する。同じ seed を使い、steps または guidance だけを変更すれば、差異はすべてそのパラメータに起因します。

画像1枚あたりの費用は料金ページに記載されています。大量の素材を処理する前に確認してください。

実際の1回の実行で確認された結果

このページに付属するサンプル部屋写真（1600×900）とその矩形マスク（白い枠は x 840–1240、y 160–580）に対して、上記の curl リクエストを1回実行しました。設定は steps: 30、guidance: 60、seed: 42、output_format: png です。

所要時間。タスクは約 25 秒間 handling 状態にあり、その後 archiving となり、エンドツーエンドで約 38 秒で success に達しました。
出力サイズは元画像と異なる。返された PNG は 1600×900 ではなく 1440×810 でした。アスペクト比は同じですが、ピクセル寸法が異なります。結果を元画像に合成し直す場合は、1:1 と仮定せず、どちらかのサイズを先に調整してください。
マスクの外側は変化しない。元画像を 1440×810 に縮小して出力と差分を取ったところ、白い枠内では 81% のピクセルが 8 段階（0–255）を超えて変化したのに対し、枠外ではわずか 0.03% のピクセルにとどまりました。マスクの端から 12 px を超える地点では、最大差は 11 段階でした。ソファ、クッション、植物、床、窓の光はいずれも再描画されていません。
プロンプトの範囲。プロンプトは絵画と保持すべき内容のみを記述しており、結果は白い枠を埋める額装された山と湖の風景でした。
誤った URL は作成時ではなくポーリング時に失敗する。image と mask を URL ではない文字列に設定した別のリクエストは 200 と taskId を返しましたが、その後タスクは約 3 秒後に status: fail と error.code: TASK_FAILED で終了しました。POST が成功したからといって入力が有効とは限らないため、必ず最終状態を確認してください。

未テスト：マスクと元画像のサイズ不一致、グレー（ソフトエッジ）値を持つマスク、アルファチャンネル付きマスク、および guidance や steps の極端な値。ドキュメントにはマスクが元画像とサイズ一致している必要があると記載されており、私は硬い二値の矩形のみをテストしました。複数の seed を実行していないため、複数回の実行間で塗りつぶしがどの程度変化するかは述べられません。

Fill Pro を選ぶべき場面

編集が自分で制御する硬い境界（製品ラベル、壁の線、衣服の縫い目など）で止まる必要がある場合に使用します。テキストで記述するマスク不要の編集には、純粋なプロンプトモデルを使用してください。画像インペインティングとオブジェクト除去ガイドでそれらを比較しています。プロンプトを書かずにマスク内の何かを消去したい場合は、Bria Eraser ガイドを参照してください。

よくある質問

`image` と `mask` はどちらも必須ですか？

はい。現在のドキュメントでは image、mask、prompt が必須とされています。

モデルはどの色を再描画しますか？

白です。黒いピクセルは元画像を保持します。

マスクは元画像と同じサイズである必要がありますか？

ドキュメントにはそう記載されています。私の実行では一致するペアを使用し、不一致のケースはテストしていません。

出力のサイズはどのようになりますか？

私の実行では、1600×900 の元画像からアスペクト比が同じ 1440×810 の PNG が返されました。

タグインペインティング画像編集

すべての記事を見る →