チュートリアル

FLUX.1 Fill Pro API の使い方：5 分で最初のマスク再描画を完走する

マスクの 4 つの厳守事項、オンライン試用 4 ステップ、API 連携 4 ステップ。そのまま実行できる curl と Python 付き。

Oct 28, 2026

TL;DR

これは何か：Black Forest Labs のマスクによる局所再描画モデルです。元画像、同サイズの白黒マスク、プロンプトをアップロードすると、白い領域だけを再描画し、黒い領域はそのまま保持します。すでに HiAPI で公開中で、モデルページを開くとすぐ試せます。新規ユーザーは登録で 200 クレジット進呈。
料金：1 枚 $0.0715（143 クレジット）。成功した画像生成のみ課金され、steps・guidance・seed・出力形式はどれも追加料金なし。失敗時は事前に引かれた分が返金されます。$10 で約 139 枚。
最短の呼び出し方：POST https://api.hiapi.ai/v1/tasks を実行し、model に flux-1-fill-pro を指定、input に image・mask・prompt の 3 フィールドを入れます。taskId を取得したらポーリングするかコールバックを待ち、data.output[0].url をダウンロードします。

マスク再描画で最もつまずきやすいのはパラメータではなく素材です。マスクは必ず元画像と同じサイズにし、白は変更したい箇所だけを覆います。以下ではまずこの 2 点をはっきりさせ、そのあとで最初の 1 枚を生成します。

FLUX.1 Fill Pro とは？

「自分で囲った部分だけを変える」編集モデルです。変更範囲は文字ではなくマスクで決まるため、隣の家具や影、地平線が一緒に変わることはありません。

マスクは掛け時計のある壁面の小さな一区画だけを覆っており、出力は 1440 × 810。左側のタペストリー、編み皿、バイソンの頭骨、観葉植物、ソファ、光はどれも再描画されていません。

入力は 3 つ。 元画像（JPEG / PNG / GIF / WebP）、同サイズの白黒マスク、プロンプト（最大 4,000 文字）。
境界を制御できる。 白は再描画、黒は保持で、変更はマスクの縁で止まります。商品のレタッチ、背景の差し替え、衣類の色替えなど「1 箇所だけ動かす」作業に適しています。
出力は元画像に追随。 アスペクト比のパラメータはなく、比率は元画像をそのまま踏襲。1600 × 900 の元画像は 1440 × 810 で返り、32 の倍数に微調整されます。
パラメータは十分かつシンプル。 steps は 15〜50 でデフォルト 50、guidance は 1.5〜100 でデフォルト 60、seed と jpg / png 出力は任意指定。

A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.

このプロンプトで生成 → リンクはプロンプトを事前入力するだけです。元画像の枠は空で、マスクの枠にはサンプルのマスクが既定で入っています。自分の元画像と同サイズのマスクに差し替えてから実行してください。

マスクの準備方法

要点は 4 つ、この順で行います：

白黒の 2 値のみ。 白が再描画する領域、黒が保持する領域です。グレーの縁があると境界がぼやけるため、できるだけ硬いエッジにします。
サイズは元画像と完全に一致。 1600 × 900 の元画像には 1600 × 900 のマスクを合わせます。スクリーンショットを撮ってから縮尺し直すのではなく、同じファイルから直接マスクを書き出してください。幅や高さが合わないとタスクは失敗します。
白い領域は対象にぴったり合わせる。 変更したいものを覆ったらそこで止め、隣の家具や天板、影を巻き込まないようにします。
元画像の解像度で PNG を書き出す。 PNG は圧縮ノイズがなく境界が最もきれいです。マスクと元画像は公網からアクセスできるアドレスに置いてください。API が受け取るのは URL であり、ファイルアップロードではありません。

黒は保持、白は再描画。この 1600 × 900 のマスクは掛け時計の位置に白い枠を 1 つだけ残しているため、その壁面だけが再描画されます。

オンラインで試す：4 ステップで最初の 1 枚

モデルページではマスクを描けません。マスクは自分のツールで作ってからアップロードします。

FLUX.1 Fill Pro モデルページを開き、登録またはログインします。新規アカウントには 200 クレジットが付きます。
元画像をアップロードし、続けて同サイズの白黒マスクをアップロードします。
プロンプトを貼り付け、白い領域に現れる内容だけを記述し、必ず保持したいものも明記します。
実行をクリック。デフォルトは steps 50、guidance 60、jpg 出力です。まず通してからパラメータを調整します。

「このプロンプトで生成」をクリックしてページを開くと、プロンプトが自動で入力されます。元画像の枠は空で、マスクの枠にはサンプルのマスクが既定で入っているので、自分のマスクに差し替えてから実行してください。

API 連携：4 ステップ

コンソールで API Key（sk-...）を作成します。
POST /v1/tasks でタスクを作成し、input に image・mask・prompt を含めます。
GET /v1/tasks/{taskId} で問い合わせるか、リクエストに callback.url を追加して通知を待ちます。
data.status が success になったら、data.output[0].url から画像をダウンロードし、すぐ自分のストレージに保存します。

完全なフィールド表、エラーコード、パラメータの説明は中国語ドキュメントをご覧ください。

最初のマスク再描画：curl 版

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
      "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
      "steps": 50,
      "guidance": 60,
      "output_format": "png"
    }
  }'

返却されるタスク ID は data.taskId にあります：

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

結果の問い合わせ：

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

上記の 2 枚の画像は 1 対 1 の比較素材です。1600 × 900 の元画像と同サイズのマスクで、そのまま実行すればこの記事の最初の掛け絵の効果が得られます。

最初のマスク再描画：Python 版

作成・ポーリング・ダウンロードを一度に書き上げています。自分の Key に差し替えれば実行できます：

import requests, time

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

payload = {
    "model": "flux-1-fill-pro",
    "input": {
        "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
        "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
        "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
        "steps": 50,
        "guidance": 60,
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(3)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("fill-pro-edit.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

パラメータの調整方法

一度に 1 つだけ変えましょう。違いが出て初めて、どの項目が効いたのか分かります。

steps（15〜50、デフォルト 50）：値が高いほど細部が細かくなります。デフォルトで仕上げには十分で、下げるのは速度を優先するときだけです。
guidance（1.5〜100、デフォルト 60）：値が高いほどプロンプトに忠実になります。スタイルがずれたらまず上げ、画面が硬くなったら戻します。
seed：仕上がりが決まったら値を固定すると、同じ画像・同じマスク・同じプロンプトで近い結果に戻せます。ロールバックやバッチの統一に便利です。
output_format：デフォルトは jpg。細部を最大限残したい場合や、後でさらに加工する場合は png を指定します。
prompt_upsampling：デフォルトは false。有効にするとプロンプトが自動で書き換えられます。文言を完全に制御したい場合はオフのままにします。

公開前に注意すべき 4 点

ページ内ではマスクを描けない。 モデルページも API も完成したマスク画像しか受け取らず、サイズも元画像と一致している必要があります。マスクは Photoshop、Figma、セグメンテーションツールで作ってからアップロードしてください。ページ上ではアップロードのみで、描画はできません。
サーバー側ではコールバックを使う。 リクエストボディに "callback": {"url": "https://yourapp.com/webhook", "when": "final"} を追加すると、タスク終了時に自動通知され、ポーリングより楽です。ポーリングはフォールバックとして残しておきましょう。
タイムアウト時に POST を繰り返さない。 POST /v1/tasks は毎回新しいタスクを作成し、個別に課金されます。先に taskId を保存し、リトライ時は同じタスクを再利用して問い合わせてください。
出力 URL は期限切れになる。 結果を取得したらすぐダウンロードしてファイルに保存し、URL を恒久的なアドレスとして扱わないでください。また出力の比率は元画像に追随し、アスペクト比のパラメータはありません。固定の版位が必要なら自分で比率に合わせて切り抜きます。

よくある質問

マスクなしで使えますか？ 使えません。image・mask・prompt の 3 つはすべて必須で、マスクは元画像と同サイズの白黒画像である必要があります。

プロンプトはどれくらいの長さにすべき？ 最大 4,000 文字ですが、必要十分で構いません。1 文で白い領域に現れる内容を、もう 1 文で必ず保持するものを書きます。細部の記述が具体的なほど結果が安定します。

出力サイズは元画像と同じですか？ 比率は一致しますが、ピクセルは 32 の倍数に微調整されます。1600 × 900 の元画像は 1440 × 810 で返るため、元画像に重ねる場合は先にサイズを揃えてください。

生成に失敗したら課金されますか？ されません。失敗したタスクの事前に引かれた金額は自動で全額返金されます。

今すぐ最初の 1 枚を

上記の 2 枚の比較素材（元画像＋マスク）はそのまま練習に使えます。curl のリクエストボディをコピーして自分の API Key に差し替えて 1 回実行するか、モデルページを開いてこの 2 枚をアップロードしてください。プロンプトはすでに入力済みなので、実行をクリックすれば同じ結果になります。1 枚 $0.0715 で、登録時に進呈される 200 クレジットで 1 枚生成できます。