チュートリアル
HiAPI API で fibo-edit-1.5 のイメージ・トゥ・イメージを呼び出す方法:curl と Python ガイド
指示ベースの画像編集のための、動作するリクエスト実践解説
このページの内容
fibo-edit-1.5 イメージ・トゥ・イメージエンドポイントでできること
fibo-edit-1.5/image-to-image は指示駆動の画像編集エンドポイントです。シーンをゼロから記述するのではなく、参照画像と自然言語の指示を受け取り、その編集を適用しつつ残りの構図を保った新しい画像を返します。
この位置づけは、リクエストの設計方法に直接影響します。参照画像は視覚的なコンテキスト——被写体、フレーミング、ライティング、スタイル——を担い、指示は変更内容を担います。よい指示は何を変えるかを明確に述べ、変えない部分についてはあえて触れません。「空を曇りのある夕焼けに置き換え、建物と前景はそのままにする」は「もっとよく見えるようにして」よりも多くの情報を伝えます。
成功した呼び出しは編集済みの画像アセットを生成します。エンドポイントの呼び出し方法に応じて、レスポンスは保存または取得できる形で生成結果を返します。正確なレスポンス構造とサポートされるパラメータについてはエンドポイントリファレンスを参照してください。フィールド名、受け付け可能な画像形式、サイズ制限といった詳細は本文書とは独立して進化する可能性があるため、そのリファレンスを唯一の権威ある情報源と考えてください。
典型的な用途には、商品写真のレタッチ、背景の置き換え、スタイル調整、そして画像全体の再生成では忠実度が損なわれる部分編集などがあります。タスクがテキストからの生成のみで編集を伴わない場合、このエンドポイントは適切なツールではありません。テキスト・トゥ・イメージモデルを使用してください。
早い段階で持っておくべき期待があります。編集は本質的に反復的なものです。最初の指示が完璧に決まることはほとんどないため、低コストの反復を中心にワークフローを組み立ててください。一度に一つの変数だけを変え、参照画像は固定し、次のステップに進む前に入力を比較します。
動作するリクエストの構成要素
コードを書く前に、リクエストに必要な入力を整理しましょう。fibo-edit-1.5/image-to-image への各呼び出しは、4 種類の情報を組み合わせます。
認証
すべてのリクエストは HiAPI の統一インターフェースを経由し、Authorization ヘッダーに API キーを含めます。キーはソースコードではなく環境変数に置き、決してコミットしないでください。
参照画像
編集対象となるソース画像を提供する必要があります。一般的な形式は 2 つあります。サービスが取得可能な公開 URL か、JSON リクエストボディに埋め込む base64 エンコードデータです。URL は反復に便利で、base64 は外部ホスティングへの依存を避けられます。どの形式が受け付けられるか、またサイズや解像度の制約についてはエンドポイントリファレンスを参照してください。
編集指示
変更内容を記述した平易な言語の文字列です。命令文として書き、変更する領域や要素を指定し、保持すべきものを明示してください。無関係な複数の編集を 1 つの指示に詰め込まないでください。それらを複数回の呼び出しに分割すれば、どれが悪い結果の原因かを判断できます。
出力制御
サイズ、出力形式、候補画像数などの任意の調整項目です。最初の呼び出しではデフォルト値のままにし、その後は意識的に調整してください。設定するパラメータはそれぞれ、問題発生時に切り分けるべき変数がまた 1 つ増えることを意味します。
したがって、最小限のリクエストボディは 2 つの実質的なフィールド——画像と指示——を JSON オブジェクトで包み、必要に応じて出力設定を加えたものになります。「どの画像を、何に変え、どの形式で返してほしいか」に答えられれば、その呼び出しを書く準備は整っています。
curl で呼び出す
まず curl から始めましょう。HTTP 層を切り離せるため、問題が起きたときにそれがアプリケーションコードではなくリクエストにあると分かります。
最初にキーをエクスポートします:
export HIAPI_API_KEY="your-api-key"
次に参照画像 URL と指示を含む JSON ボディを送信します:
curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/input.jpg",
"prompt": "平坦な空を柔らかな夕焼けのグラデーションに置き換える。建物と前景はそのままにする。"
}'
実用的なヒントをいくつか:
- ベース URL とパスは記憶からコピーせず、エンドポイントリファレンスで確認してください。
-sSを使うと、成功時は静かにしつつ転送エラーは表示されます。- 外部ホスティングに依存したくない場合は、ファイルを base64 エンコードして
imageの値をエンコード済み文字列に置き換え、リファレンスで指定されたフィールド名に合わせてください。 - 探索段階では出力を
jq .にパイプすると、レスポンスが読みやすくなります。
レスポンスを確認するには、返された画像ペイロードまたは URL を探して開いてください。レスポンスボディがエラーオブジェクトの場合は、type と message フィールドを記録します。これらのフィールドは、問題が画像、指示、リクエスト構造のどこにあるかを教えてくれます。成功した生のレスポンスをファイルに保存してください。Python クライアントを書く際のテストフィクスチャとなり、将来の挙動変更の証拠にもなります。
同じリクエストを Python で行う
Python 版は curl 呼び出しと完全に一致させるべきです。同じパス、同じヘッダー、同じボディです。そうすれば差分はリクエスト内容の違いではなく、コードのバグになります。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"
payload = {
"image": "https://example.com/input.jpg",
"prompt": (
"平坦な空を柔らかな夕焼けのグラデーションに置き換え、"
"建物と前景はそのままにする。"
),
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
ローカルファイルを送信する
ディスク上のファイルを編集する場合は、URL ではなく文字列としてエンコードして送信します:
import base64
with open("input.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"image": encoded,
"prompt": "背景を清潔なニュートラルグレーに変更する。商品はくっきり保つ。",
}
この方法に依存する前に、エンドポイントリファレンスで正確なフィールド名と想定されるエンコーディングを確認してください。
出力を保存する
返された画像をディスクに書き出せば、反復結果を並べて比較し、どの指示がどの結果を生んだかを記録できます。指示のハッシュから生成した名前で出力を保存する小さなヘルパー関数があれば、後での比較が簡単になります。
明示的な timeout を必ず設定してください。画像編集は単純なテキスト呼び出しより時間がかかり、タイムアウトのないリクエストはネットワークの停滞時にワーカープロセスを無期限に停止させます。
エラーを処理し安全にリトライする
失敗はいくつかの大きなカテゴリに分類でき、それぞれ異なる対応が必要です。
クライアントエラー
リクエスト自体に誤りがあります:JSON の形式エラー、画像フィールドの欠落、サポートされない画像形式、モデルが実行できない指示、または認証の問題です。これらをそのままリトライしても時間とクォータを浪費するだけで、まったく同じように失敗します。代わりにリクエストを修正してください。この種のエラーが発生したら、完全なリクエストボディ(画像部分は切り詰める)とエラーメッセージを記録し、入力を修正してください。
レート制限
許可された量を超える速度でリクエストを送信しています。正しい対応はバックオフしてリトライすることで、エンドポイントを叩き続けることではありません。レスポンスにリトライのヒントがあればそれに従い、なければ指数バックオフを使用してください。
サーバーエラーと一時的エラー
タイムアウト、接続リセット、上流の障害はリトライする価値があります。ここで冪等なリトライロジックが役立ちます。
実用的なリトライ戦略
- タイムアウト、接続エラー、およびレート制限やサーバーからのレスポンスの場合にのみリトライします。
- 上限付きの指数バックオフを使います。たとえば短い遅延から始めて試行ごとに倍にし、少数の固定回数で停止します。
- 並列ワーカーが同じ瞬間に一斉リトライしないよう、遅延にジッターを加えます。
- スキーマ、形式、指示の問題で拒否されたリクエストは決してリトライしません。
- 各試行とその試行回数・結果を記録し、失敗が集中しているかどうかを把握できるようにします。
import random, time, requests
def edit_with_retry(payload, attempts=4):
delay = 1.0
for i in range(attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if r.status_code < 400:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
r.raise_for_status()
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 2, 30)
raise RuntimeError("リトライ後も編集に失敗しました")
これは骨組みとして扱ってください。リトライ可能なステータスコードをエンドポイントが実際に返すものに合わせ、ポリシーを 1 か所に集約してすべての呼び出し元で共有します。
本番投入前のチェック
エンドポイントを本番環境に接続する前に、短いチェックリストを完了してください。
正常系を 2 回検証する
保存した curl 呼び出しと Python クライアントを同じ入力に対して再実行し、同等の結果が得られることを確認します。両者が食い違う場合、リクエストボディが実際には同一ではありません。
実際の入力で指示を調整する
単一のサンプルだけでなく、代表的な画像で指示をテストします。編集品質は、指示の具体性と参照画像がその変更をどの程度支えるかに大きく依存します。小さなプロンプトと出力のペアを回帰テストスイートとして保持しておけば、言い回しを調整したときに何が改善し何が後退したかが分かります。
制限と形式を確認する
エンドポイントリファレンスで、受け付け可能な画像形式、最大サイズ、およびリクエストサイズの上限を確認します。送信前にローカルで検証してください。クライアント側で悪い画像を弾く方が、往復するよりも速く安価です。
キーとログを確認する
API キーが環境変数から取得されていること、リクエストログで画像ペイロードが切り詰められること、エラーレポートにキーが現れないことを確認します。
失敗時の挙動を確認する
ステージング環境でタイムアウトと不正な形式のリクエストボディを意図的に発生させ、リトライポリシーが正しく動作すること、および恒久的な失敗が呼び出し元に表面化して黙って消えないことを確認します。
これらすべてが通れば、この統合はよい意味で平凡になります。権威あるパラメータ一覧はfibo-edit-1.5 イメージ・トゥ・イメージエンドポイントリファレンスから取得し、動作する curl 呼び出しから外側へ向けて構築してください。