HiAPI
ブログ

チュートリアル

HiAPI API で flux-1-fill-pro を呼び出す方法:curl、Python、非同期ポーリング

Nov 12, 2026
HiAPI ブログのカバー画像:濃紺の背景に、三層に入れ子になった幅広の矢印形が水平方向へ段階的に進み、先端はアプリコットオレンジ色で、フラットな信号フロー図のスタイル。
このページの内容

flux-1-fill-pro の役割と適したユースケース

flux-1-fill-pro はインペイント系の画像編集モデルです。ソース画像と、再生成したい領域を示すマスクを渡すと、その領域が置き換えられた新しい画像を出力します。マスクの外側は変わらないはずで、これが純粋なテキストto画像モデルや全画像スタイル変換モデルとの違いです。

編集が局所的で、周囲のコンテキストが重要な場合に使うべきです:

  • オブジェクト除去 —— 不要な要素をマスクで囲み、その背後にあるはずの内容をモデルに再構築させます。
  • オブジェクト置換 —— マスクで領域を指定し、プロンプトで新しい内容を記述しながら、シーンの残りの部分は変えません。
  • ローカル修復 —— 画像全体を再生成せずに、テクスチャや反射、小さな瑕疵を修正します。
  • パイプラインへの挿入 —— 商品画像やサムネイル、生成素材のうち、1つの領域だけを後処理する必要がある場合に、プログラムで修正します。

プロンプトから全く新しい構図を得たい場合や、マスク領域が大きすぎてモデルが実質的にゼロから画像を生成している場合には適したツールではありません。そのような場合は、標準の生成エンドポイントの方がより予測可能な動作をします。

本ガイドの残りの部分では、HiAPI API を通じて flux-1-fill-pro をコードに組み込む方法を扱います:リクエスト構造、curl 呼び出し、Python での同等の書き方、そして初めての統合で多くの人がつまずく非同期タスクの処理です。

準備と認証の設定

最初のリクエストを送る前に、3つのことを確認してください。

API キー

HiAPI アカウントでキーを作成し、ソース管理から遠ざけてください。以下の例では環境変数から読み込むため、これらのスニペットは安全にコピーできます:

export HIAPI_API_KEY="your_key_here"

Python では os.environ を通じて同じ方法で読み込みます。CI で実行する場合は、.env ファイルをコミットするのではなく、シークレットとして注入してください。

モデル識別子

すべてのリクエストはモデルを名前で指定します。本ガイドでは識別子は flux-1-fill-pro です。文字列リテラルを散らかすのではなく、コード内の定数として保持してください。そうすれば将来モデルを変更する際は1行変えるだけですみます。

ベース URL

すべての呼び出しは、プラットフォームのリファレンスドキュメントに記載された HiAPI API のベース URL に送信されます。キーと一緒に設定に置いておけば、ステージングと本番でコードを変えずに異なる URL を使えます。

始める前の構造的な注意点:インペイントリクエストは画像データを含みます。フォームアップロードを無理に通そうとするのではなく、base64 エンコードした画像を JSON として送信してください。また、クライアントのリクエストタイムアウトには十分な余裕を持たせてください。大きな画像のエンコードは、リクエストがプロセスを離れる前にレイテンシを増やします。現在のペイロードサイズ制限についてはプラットフォームのドキュメントを確認してください。ソース画像がドキュメントの上限を超える場合は、リクエストがエッジで失敗するのを待つのではなく、エンコード前に縮小してください。

インペイントリクエストの構造

どの言語で書いても、flux-1-fill-pro の呼び出しは同じ論理構成を持ちます。

ソース画像

編集する画像で、文字列としてエンコードされます。これがキャンバスを定義します:その寸法がマスクの座標空間を決定し、その内容がモデルに信憑性のあるインペイントを行わせるためのコンテキストを提供します。

マスク

マスクはどの領域が再生成されるかを示します。これが最もよくある混乱の原因なので、ペイロードがどの慣習に従うかを明確にしてください:マスクでマークされた領域がモデルに変更を許可する領域です。マスクを別の画像として作成し、埋める領域と保持する領域を視覚的に明確に区別できるようにしてください。マスクを反転させるのは典型的なバグです。そうすると、望んだ領域以外のすべてをモデルが編集した結果が得られます。

マスクはソース画像と寸法が完全に一致しなければなりません。異なる解像度で描かれたマスクは拒否されるか、静かにずれてしまい、どちらの結果も往復を無駄にします。

プロンプト

マスク内に何が現れるべきかを記述するテキストです。具体的かつ局所的に保ってください:シーン全体ではなく、内容と、周囲との光やテクスチャの関係を記述します。「店舗の見切りに沿った木製ベンチ、左から柔らかい午後の光」は「もっと良い背景」よりもモデルに多くの根拠を与えます。

任意の制御項目

ドキュメント化されたパラメータセットによっては、再現用の seed や、インペイントが元のピクセルからどれだけ逸脱できるかを制御する強度系のパラメータも渡せるかもしれません。現在のリファレンスドキュメントに存在しないパラメータは、名前を推測するのではなく、サポートされていないものとして扱ってください。

これら4つ——モデル、プロンプト、ソース画像、マスク——はすべて同じ JSON ボディで渡されます。次の2つのセクションではこのボディを送信します。

動作する curl リクエスト

まず curl から始めましょう。そうすれば、クライアントライブラリが覆い隠す前に生のエンベロープを確認できます。

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

ここで request.json は次のようになります:

{
  "model": "flux-1-fill-pro",
  "prompt": "店舗の見切りに沿った木製ベンチ、左から柔らかい午後の光",
  "image": "<base64-encoded source image>",
  "mask": "<base64-encoded mask image>"
}

このファイルを構築するには2つの実用的なコツがあります。第一に、手で貼り付けるのではなく、コマンドで base64 ペイロードを生成してください:

base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64

次に、小さな jq または Python のステップでそれらを結合し、request.json を組み立てます。数メガバイトの base64 ブロックを手作業で JSON に編集するのは、ペイロードの切り詰めや不可解な 400 エラーの原因になります。

レスポンスの解釈

レスポンスのエンベロープが次に何をすべきかを教えてくれます。完了したタスクは編集済み画像を返します——通常は URL または base64 フィールドで、現在のリファレンスドキュメントが定める形式に従います。キューに入ったタスクは識別子とステータスを返し、その後あなたがポーリングします(後述)。最初のレスポンスが常にピクセルを含むと仮定しないでください。初日から両方の形態を扱えるパーサーを書いておかないと、負荷がかかってタスクがキューに入った最初の時に書き直すことになります。

レスポンスボディを解析する前に HTTP ステータスコードを確認してください。4xx はリクエスト自体が誤っていることを意味し、リトライしても無駄です。代わりにペイロードを修正してください。

同じ呼び出しを Python で実装

Python 版は同じリクエストですが、より扱いやすいです。SDK は不要で、requests で HiAPI エンドポイントにリクエストするだけで十分です。

import base64
import json
import os
import time

import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"


def b64(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("ascii")


def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": b64(source_path),
        "mask": b64(mask_path),
    }
    resp = requests.post(
        f"{BASE_URL}/v1/images/edits",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(payload),
        timeout=120,
    )
    if resp.status_code >= 400:
        raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
    return resp.json()

timeout は意図的に設定しています。大きな画像のエンコードとアップロードは典型的な JSON 呼び出しよりも時間がかかり、無制限のリクエストはバッチタスクでスクリプトが静かにハングする原因になります。4xx 時にレスポンスボディ付きで例外を送出すれば、不可解な失敗を読める失敗に変えられます。

モデル識別子とエンドポイントはモジュールレベルの設定に置き、バージョンアップが1箇所の変更で済むようにしてください。大量の画像を処理する場合は、requests.Session を再利用して接続をプールし、呼び出しごとに張り直さないようにしてください。

解析された辞書は、完了済みの結果か、ジョブハンドルのいずれかです。後者は次のセクションで扱います。

非同期タスクとポーリングの処理

インペイントリクエストは遅くなることがあるため、API は完成画像ではなくジョブハンドルを返す場合があります。正しいパターンは、固定の sleep の後に祈るのではなく、有界なポーリングループです。

ループ

def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
    deadline = time.monotonic() + timeout
    current = job
    while time.monotonic() < deadline:
        status = current.get("status")
        if status in {"succeeded", "completed"}:
            return current
        if status in {"failed", "canceled", "cancelled"}:
            raise RuntimeError(f"Job ended as {status}: {current}")
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)  # 穏やかなバックオフ
        current = fetch_job(current["id"])
    raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")

fetch_job は上記と同じリクエストパターンで、ジョブ id と認証ヘッダーを使ってドキュメント化されたジョブステータスエンドポイントにアクセスします。

固定間隔ではなくバックオフを使う理由

キューに対してタイトループでポーリングすると、何の利益もなく API を無駄に叩き続けます。短い間隔から始めて上限まで倍々に増やすことで、早期の完了には素早く反応しつつ、遅いジョブで何千回も無駄なポーリングをしません。間隔に上限を設ければ、完了を数秒以内に検知できます。

タイムアウトと失敗が別物である理由

タイムアウトはあなたが待つのをやめたことを意味し、ジョブが失敗したわけではありません。例外を送出する際はジョブ id を保持してください。そうすれば呼び出し側は後でポーリングを再開でき、同じ作業を再提出して二重に課金する必要がありません。パイプラインではタイムアウト、ジョブ失敗、HTTP エラーを3つの異なる例外として扱ってください。それらを1つの汎用エラーにまとめると、本番障害の調査がずっと難しくなります。

よくある障害のデバッグ

ほとんどのエラーレスポンスはいくつかのカテゴリに収まります。順に確認してください。

401 / 403 —— 認証

まず確認:ヘッダーは正確に Authorization: Bearer <key> になっていますか?引用符も、エクスポートされていないシェル変数由来の余分な空白もありませんか? 空の $HIAPI_API_KEY は Bearer という単語だけの Bearer トークンを生成し、誤ったキーと同じように失敗します。

400 —— ペイロード形式の誤り

まず確認:base64 文字列を連結した後、リクエストボディはまだ有効な JSON ですか? request.json をエクスポートし、python -m json.tool にかけてみてください。画像フィールドに data:image/png;base64, プレフィックスが付いているのはよくある原因です——リファレンスドキュメントが明示的に要求しない限り、それらを取り除いてください。

マスク/画像の不一致

まず確認:マスクとソース画像のピクセル寸法は完全に一致していますか? 次に極性を確認してください——白い領域がモデルに再生成してほしい領域であることを確かめてください。結果が要求したものと逆に見える場合は、ほぼ常にマスクの反転であり、プロンプトの問題ではありません。

プロンプトの過剰

マスクされていない領域が変化した場合、またはインペイントがグローバルに見える場合、マスクが大きすぎるか、プロンプトがシーン全体を覆いすぎている可能性があります。両方を狭めてください:マスクを実際の編集領域に絞り、マスク内の内容だけを記述します。

ジョブのタイムアウト

まず確認:ペイロードサイズ。大きすぎるソース画像が、ジョブが完了しない最も一般的な原因です。まず縮小して一度リトライし、それでもタイムアウトする場合は、小さなテスト画像でリファレンスの制限と照合してから、サービス側の問題と仮定してください。

結果フィールドが空または欠落

まず確認:キュー応答の形態を処理しましたか? 完了形態だけを読むパーサーは、最初の呼び出しで何も見つけられません。開発中は完全なレスポンスエンベロープをログに記録し、防御的なコードを書く前に形態を把握できるようにしてください。

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む