HiAPI
ブログ

チュートリアル

HiAPI API で flux-2/image-to-image を使う:curl と Python のチュートリアル

Nov 12, 2026
カバー画像:深い松葉色の背景にいくつかの大きなプリズムが斜めに切り取られて平らな色面となり、青緑と霞んだ緑の幾何学的な切り口が簡潔で整然としている。
このページの内容

flux-2/image-to-image の役割と適切なユースケース

flux-2/image-to-image は純粋なテキストからの画像生成器ではなく、編集用エンドポイントです。渡すべきものは 2 つあります。参照画像と、自然言語で書かれた編集指示です。モデルは参照画像を視覚的なコンテキスト(被写体、構図、スタイル、照明)として読み取り、あなたの指示に従いつつ参照画像にアンカーされた新しい画像を生成します。

パイプラインを設計する際、この違いは重要です。テキストからの画像生成では、すべてをゼロから記述し、モデルが意図の近くに落ち着くことを期待します。画像から画像への生成では、すでに視覚的な素材があり、欲しいのは制御された変換です。商品画像のスタイルを変える、背景を差し替える、シーンの雰囲気を調整する、あるいは土台の構図を安定させたままデザインを反復する、といったことです。

適した場面

  • 素材のバリエーション。 承認済みの参照画像 1 枚から複数のスタイル処理を生成する。
  • ガイド付き編集。 シーン全体を再生成せずに、狙った変更(「光をより暖かく」「背景を無地のスタジオ壁に」)を適用する。
  • 結果セットの一貫性。 同じ参照画像を再利用し、一連の出力が同じ視覚的アンカーを共有するようにする。
  • 人間と機械の協働ツール。 ユーザーに画像をアップロードさせ、修正内容を記述させ、あなた自身の UI 上で結果を受け取る。

適さない場面

  • ピクセル単位で正確なレタッチや合成。これは生成モデルであり、ラスター画像エディタではありません。
  • 参照画像がまったくない場合。その場合はテキストからの画像生成の方が良い出発点です。
  • 指示だけですべての詳細を担うことを要求するワークフロー。参照画像は実際に機能しており、悪い参照画像からは悪い結果しか生まれません。

このエンドポイントは 参照画像 + 指示 -> 編集後の画像 と捉えてください。本チュートリアルのすべてはこの形の上に成り立っています。どう送るか、返ってきた結果をどう読むか、ネットワークが言うことを聞かないときにどう動かし続けるか、です。

前提条件と認証の設定

最初の呼び出しの前に、3 つ準備してください。

1. HiAPI アカウント

登録してコンソールを開きます。本チュートリアルのすべてのリクエストは HiAPI の統合 API 経由で送られるため、プロバイダごとに個別登録したり、SDK をインストールしたりする必要はありません。

2. API キー

コンソールで API キーを作成します。パスワードと同じように扱ってください。コードリポジトリにコミットせず、クライアントコードに貼り付けず、ログにも残さないこと。標準的な方法は実行時に環境変数から読み込むことです:

export HIAPI_API_KEY="your-api-key-here"

その後、キーが必要な箇所で HIAPI_API_KEY を参照します。コンテナやサーバーレスプラットフォームにデプロイする場合、イメージに焼き込むのではなく、その環境のシークレットとして設定してください。

3. アクセス可能な参照画像

このエンドポイントは参照画像を必要とするため、どう提供するかを事前に決めておきます。よくある 2 つの方法:

  • URL。API が取得できるもの、例えばあなた自身のオブジェクトストレージへの署名付きリンク。
  • Base64 エンコードされたバイト列。リクエストボディにインラインで送ることで、内部 URL を露出せずに済みますが、ペイロードは大きくなります。

まずは小さなテスト画像を選んでください。数百 KB あれば統合の検証には十分です。大きなファイルのアップロードは毎回のリトライを遅くし、デバッグも難しくします。

チェックポイント

ここまでで、環境変数に保存したキーと、ローカルからアクセスできるテスト画像が用意できているはずです。できればキーがシェル履歴に残らないようにしてください(ツールが読み込む .env ファイルの方が、コマンドラインにインラインで export するよりたいていきれいです)。

もう 1 つ、今から身につけておく価値のある習慣があります。初日からリクエスト ID と所要時間を記録することです。本番で問題が起きたとき、追跡できるリクエストとできないリクエストの差は甚大です。

リクエストの組み立て:参照画像と編集指示

画像から画像への呼び出しはすべて 2 つの入力の周りに組み立てられます。この 2 つを正しくやれば、残りは配管作業です。

入力 1:参照画像

参照画像はアンカーです。編集前のシーンに何があり、どう見えるかをモデルに伝えます。実用的なアドバイス:

  • 欲しい出力のアスペクト比に合わせる。 参照画像が横長で正方形の出力が必要な場合、呼び出しの設定によってはクロップや歪みが発生することを想定してください。
  • クリーンで照明の良い画像から始める。 濁った参照画像からは濁った編集結果しか生まれません。
  • 明確な被写体が 1 つだけであるのが望ましい。 雑然としたコラージュは、モデルに競合するアンカーを多すぎるほど与えてしまいます。

入力 2:編集指示

指示とは、欲しい変更の自然言語による記述です。品質の差のほとんどはここから生まれます。参照画像が添付されたプロンプトだと考えてください。

  • シーン全体ではなく、変更を述べる。 「背景を純白のスタジオ壁に変える」は「白い背景の商品」より優れています。後者はモデルにすべてを描き直させる誘因になります。
  • 保持すべきものを明示する。 「被写体のポーズと構図は変えないでください」のような表現はドリフトを大幅に減らします。
  • スタイルと照明を具体的に指定する。 「柔らかな曇天の光、低彩度の色合い」は「もっと良く見せて」よりもモデルに多くの有用な情報を与えます。
  • 矛盾を避ける。 参照画像が昼間の屋外シーンなのに、夜の室内を要求すると、モデルがあなたの好まない判断を下すことを想定してください。

リクエストボディ

flux-2/image-to-image に送るリクエストには、モデル識別子、参照画像、指示が含まれます。有用なメンタルモデル:

{
  "model": "flux-2/image-to-image",
  "input": {
    "image": "<URL または base64 の参照画像>",
    "prompt": "<編集指示>"
  }
}

参照画像が base64 の場合、リクエストスキーマに従って data URI として構築するか、生のエンコードを MIME タイプと一緒に渡します。URL の場合は、呼び出し中にそのリンクが公開アクセス可能であることを確認してください。リクエストの途中で期限切れになる署名付きリンクは、理解しにくい失敗を生みます。

まず反復、次に統合

何かをコードに組み込む前に、同じ参照画像に対して 2〜3 の指示を書いて出力を比較してください。指示が具体的なときモデルは予測可能に振る舞い、曖昧なときは不安定になります。これを今学ぶ方が本番で学ぶよりずっと安上がりです。

実際に動く curl リクエスト

キー、参照画像、指示を検証する最速の方法は curl 呼び出し 1 回です。以下の例では、キーが HIAPI_API_KEY にあり、参照画像が URL でアクセス可能であることを前提としています。

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "image": "https://your-bucket.example.com/reference.jpg",
      "prompt": "背景を純白のスタジオ壁に変えてください。被写体のポーズ、構図、および被写体に当たっている光は変えないでください。"
    }
  }'

注意すべき点がいくつかあります:

  • キーは Authorization ヘッダーで bearer トークンとして送信されます。絶対に URL に入れないでください。
  • Content-Type は JSON です。 これを設定し忘れるのは、紛らわしい 4xx のよくある原因です。
  • モデル id はリクエストボディに入ります。 そのため同じエンドポイントで 1 つのフィールドを変えるだけで別のモデルにルーティングできます。
  • 指示はキーワードのリストではなく完全な文です。 これは意図的なものです。前のセクションを参照してください。

生の出力を読む

まず 1 回実行し、解析コードを書く前にレスポンス全体を確認してください。必要なら整形ツールを通します:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

リクエストボディをファイル(request.json)に保存すると、シェルのクォート文字列を編集するより反復が楽になり、後でバグを再現できる永続的な成果物にもなります。

URL ではなく base64 が必要な場合

image の値を、ファイルから構築した data URI に置き換えます:

python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
    "model": "flux-2/image-to-image",
    "input": {
        "image": f"data:image/jpeg;base64,{data}",
        "prompt": "光をより暖かくし、コントラストを少し下げてください。",
    },
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY

ペイロードが request.json に保存されているので、同じ curl 呼び出しがそのまま機能します。呼び出しが成功すれば、Python に移行するための準備はすべて整っています。

同じ呼び出しを Python で

Python 版はあえて地味にしています。同じ辞書を構築し、同じヘッダーで送信し、エンドポイントとモデルを定数に置くことで、curl 版との乖離を防ぎます。

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"


def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # 未設定なら即座に失敗する
    payload = {
        "model": MODEL,
        "input": {
            "image": reference_url,
            "prompt": instruction,
        },
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = edit_image(
        "https://your-bucket.example.com/reference.jpg",
        "背景を純白のスタジオ壁に変えてください。"
        "被写体のポーズ、構図、および被写体に当たっている光は変えないでください。",
    )
    print(result)

なぜこのように構成するのか

  • .get() ではなく os.environ["HIAPI_API_KEY"] を使うことで、キーがない場合は未認証のリクエストを送るのではなく即座にエラーになります。
  • timeout は明示的です。 画像生成は一瞬ではありません。タイムアウトのないリクエストは最終的にワーカープロセスをハングさせます。
  • 解析の前に raise_for_status() を呼びます。 4xx や 5xx のときは、後続のどこかで紛らわしい KeyError が出るのではなく、例外を受け取りたいからです。
  • エンドポイントとモデルはモジュールレベルの定数なので、テストスイートをスタブサーバーに向けるのが簡単になります。

base64 入力を使用する

URL ではなくバイト列を渡す場合は、ペイロードを構築するのと同じ場所でファイルをエンコードし、data URI を構築します:

import base64, pathlib

def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
    raw = pathlib.Path(path).read_bytes()
    return f"data:{mime};base64," + base64.b64encode(raw).decode()

その後 edit_image(as_data_uri("reference.jpg"), instruction) を呼び出します。エンコード処理をリクエスト関数から分離しておくことで、ネットワークに触れずに検証やプロンプト組み立てを単体テストできます。

レスポンスの解析

呼び出しは JSON オブジェクトを返しました。ここで、将来レスポンスにフィールドが増えても壊れないように編集後の画像を抽出します。

仮定せず、まず確認する

開発中は生のレスポンスを 1 回出力し、画像参照がどこにあるか(通常は結果構造の中に埋め込まれた URL または base64 ペイロード)に注意してください。その上で、ネストしたキーを直接掘るのではなく、存在をチェックするアクセサを書きます。

def extract_image_url(response: dict) -> str:
    data = response.get("data") or []
    if not data:
        raise ValueError(f"レスポンスに画像データがありません:{response}")
    first = data[0]
    url = first.get("url") or first.get("b64_json")
    if not url:
        raise ValueError(f"認識できない画像ペイロード:{first}")
    return url

このコードには残しておく価値のある習慣が 2 つあります。実際のペイロードをエラーメッセージに含めて大きく失敗すること、そしてどちらの形態(URL または base64)も受け入れることで、片方をハードコードしないことです。レスポンス形式は進化します。寛容なリーダーだけが生き残ります。

すぐに永続化する

返された URL は一時的かもしれません。画像が重要なら、同じタスク内でダウンロードし、あなた自身のバケットに保存します:

def persist(url: str, dest: str) -> None:
    if url.startswith("data:"):
        header, b64 = url.split(",", 1)
        import base64, pathlib
        pathlib.Path(dest).write_bytes(base64.b64decode(b64))
        return
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

永続化は、データベースに記録できる安定したキーも与えてくれます。これは腐敗する可能性のあるリンクを保存するよりはるかに有用です。

得られたものを検証する

安価なチェックで高価なミスを見つけられます。ファイルが空でないこと、マジックナンバーが何らかの画像形式と一致すること、可能ならサイズが期待通りであることを確認してください。壊れた画像や切り詰められた画像をユーザーに提供するより、境界で拒否する方がはるかに良いです。

来歴情報を記録する

モデル id、指示テキスト、参照画像キー、タイムスタンプを出力と一緒に保存します。3 週間後に誰かが「なぜこの画像はこう見えるのか」と尋ねたとき、その 1 行が答えになります。しかも特定の編集を再実行するのが容易になります。

本番環境でのリトライとエラーハンドリング

画像生成の呼び出しはまったく異なる理由で失敗します。それらを混同するのは典型的な本番バグです。

一時的エラーと最終的エラーを区別する

  • 一時的——タイムアウト、接続リセット、429 レート制限、5xx レスポンス。同じリクエストを休止後に再試行すれば成功する可能性が高いです。
  • 最終的——400 無効なリクエスト、401 キーが誤っているか欠落、404 不明なモデル、ペイロード検証エラー。これらを再試行すると時間とコストを浪費し、本当の修正を遅らせます。

再試行するのは 1 つ目の種類だけです。2 つ目の種類では、即座にタスクを失敗させ、エラーメッセージを露出させてください。ほぼ常にどのフィールドに問題があるかを正確に示してくれます。

バックオフとジッター付きで再試行する

import random, time, requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
    last = None
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status not in RETRYABLE:
                raise
            last = e
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        delay = base * (2 ** i) + random.uniform(0, 0.5)
        time.sleep(delay)
    raise RuntimeError("再試行回数を使い果たしました") from last

指数バックオフはすでに苦しんでいるサービスを叩き続けるのを防ぎ、ジッターはワーカー群が一斉に再試行するのを防ぎます。試行回数と総所要時間には必ず上限を設けてください。無限ループはきれいな失敗より悪いです。

レート制限を守る

429 に遭遇したら、バックオフする前にレスポンスヘッダーに含まれる再試行のヒントに従ってください。大量のジョブを実行している場合は、サーバーにスロットリングを任せるのではなく、自分側で同時実行数の制限を追加してください。

失敗を可視化する

  • リトライに一意のタスク id を付け、各試行とその結果、所要時間を記録します。
  • リトライ率のメトリクスを出力します。緩やかな上昇は上流のどこかが劣化している早期警告です。
  • 最終試行が失敗した後、タスクをデッドレターキューに移し、完全なレスポンスボディを添付します。「failed」といったメッセージだけにしないでください。

冪等性とコストの妥当性

再試行したリクエストは、クライアントがレスポンスを一度も見なかったとしても、サーバー上ではすでに成功している可能性があります。製品が重複出力を許容できない場合、独自の id でタスクにキーを付け、再試行の前に対帳を行ってください。また、呼び出しは従量課金なので、リトライループが静かにコストを増幅させることに警戒してください。詰まって永遠に再試行し続けるコンシューマーは、この点で最も高くつくバグです。

よくある落とし穴と次のステップ

flux-2/image-to-image をめぐる統合の苦労のほとんどは、小さな一連のミスから生じます。リリース前に、これらに照らしてコードを確認してください。

  • 指示が曖昧。 「もっと良くして」はランダムな結果を生み、「看板の文字を消して看板の形は保つ」は使える結果を生みます。具体性は品質への最大のテコです。
  • 参照画像の不一致。 誤ったアスペクト比、ぼやけたソース画像、雑然としたコラージュは、より良いプロンプトでは救われません。
  • 期限切れの URL。 リクエストの途中で切れる署名付きリンクは、サーバーエラーのように見える失敗を引き起こします。十分に長い有効期限を使うか、base64 に切り替えてください。
  • レスポンス構造のハードコード。 ネストしたキーを直接掘ると、小さなスキーマ変更が障害になります。明確なエラーを伴う防御的な抽出器を使ってください。
  • タイムアウトなし。 タイムアウトがないとワーカープロセスを無期限に占有し、本当の問題を覆い隠します。
  • 最終的エラーの再試行。 400 は自分では直りません。メッセージを読んでください。
  • 出力の喪失。 返された URL が一時的で画像を永続化していないなら、何も残りません。
  • シークレットやプロンプトの不注意なログ出力。 キーは絶対にログに現れてはなりません。ユーザー提供の指示は、あなたの領域によってはマスキングが必要かもしれません。

次のステップ

単一呼び出しのフローが固まったら、自然な拡張は次のとおりです。呼び出しをバックグラウンドタスクでラップして UI の応答性を保つ。指示とレスポンスのペアを保存してプロンプトの言い回しを A/B テストできるようにする。ユーザーが自分の画像を提供する場合は、入力にモデレーションや検証のレイヤーを追加する。flux-2/image-to-image のモデルページと HiAPI のドキュメントを参照して、あなたのユースケースで次に必要になりそうなパラメータを確認してください。動く最小限のものを作り、測定し、指示の品質に大任を負わせましょう。

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

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

APIドキュメントを読む