チュートリアル
HiAPI API で fibo-2.0/image-to-image を呼び出す方法:curl と Python の実践
このページの内容
fibo-2.0/image-to-image のパイプラインにおける位置づけ
テキストから画像を生成するモデルは 1 つのプロンプトから始まりますが、画像から画像を生成するモデルは、すでに手元にある画像から始まります。この違いは一見小さく見えますが、モデルがパイプラインのどこに位置するかを決定づけます。fibo-2.0/image-to-image は、最初に素材を生み出す第一歩ではなく、既存の画像を改造する編集ステップなのです。
典型的なワークフローは次のとおりです。ベースとなる画像を取得または生成し、必要な変更を記述した指示とともに fibo-2.0/image-to-image へ送り、返された結果を後続の工程(審査、合成、保存、あるいは別のモデル呼び出し)へ渡します。モデルは入力画像とプロンプトの両方を受け取るため、あなたが記述した部分のスタイルを描き直したり、調整や改造を加えたりしながら、構図、被写体の位置、全体構造を維持できます。
テキストから画像ではなく画像から画像を選ぶべき時
出力が既存の画像と識別可能な関連を保つ必要がある場合は、画像から画像を選びます。被写体を保ったまま写真のスタイルを描き直す、照明や色処理を調整する、承認済みの素材のバリエーションを生成する、あるいは最終使用前に粗い下地画像をクリーンアップする、といったケースです。手元に開始画像がなく、説明文だけしかない場合は、テキストから画像を選びます。
このインターフェースがあなたに求めるもの
この呼び出しはジョブの投入です。入力画像、プロンプト、制御したいパラメータを送信すると、API は追跡可能なジョブを返します。このインターフェースは、完全な編集アプリケーションではなく、より大きな連鎖の中の明確に定義された 1 つの段階と捉えるべきです。入力画像をどう準備し、結果をどう扱うかは、あなたの責任です。
リクエストは本質的に非同期であるため、統合設計もそれを中心に組み立てるべきです。送信し、ジョブ識別子を保存し、ジョブが完了するまでポーリングし、その後で出力参照を取得します。本ガイドの残りの部分は、まさにこのフローを構築するためのものです。
リクエスト送信前の準備
初回呼び出しの前に、3 つのものを用意する必要があります。認証情報、インターフェースの形についての正しい理解、そして準備済みの入力画像です。
認証情報
HiAPI API へのすべてのリクエストは API キーで認証されます。キーは必ずサーバー側に保管してください。ブラウザのコードに埋め込んだり、コードリポジトリにコミットしたりしてはいけません。最もクリーンな方法は環境変数から読み込むことで、同じコードをローカル環境でもデプロイ環境でもそのまま使えるようにします:
export HIAPI_API_KEY="your-api-key"
まだキーをお持ちでない場合は、まず HiAPI アカウントのコンソールで作成してから続行してください。
インターフェースの形
このモデルは HiAPI API 内で fibo-2.0/image-to-image として識別されます。すべてのモデル呼び出しは同一のベース URL とリクエスト規約を共有しており、つまり一度動作する呼び出しを手に入れれば、他のモデルへの切り替えは主にモデル識別子とペイロードのフィールドを変更するだけになります。
入力画像の準備
画像から画像へのリクエストには、実際の画像が必要であり、解釈してくれることを期待した URL では不十分です。事前に提供方法を決めておいてください。リクエストとともにアップロードするローカルファイルとしてか、API が受け付ける参照としてか。そしてアプリケーションコードを書く前に、その形式が使えることを確認してください。初回リクエストで最もよくある 2 種類の失敗は、あなたのノート PC にしか存在しないパスを送ってしまうこと、そしてインターフェースが受け付けない形式のファイルを送ってしまうことです。
呼び出しを構築する前の実用的なチェックリスト:
- その画像が、使用する言語で読み取れる実際のファイルである。
- プロンプトが、キーワードの羅列ではなく、平易な言葉で望む編集を記述している。
- どのパラメータを渡し、どれをデフォルトのままにするかを把握している。
- リクエストを発行する環境から API キーが見つかる。
これらが整えば、リクエスト本体へ進めます。
動作する curl リクエストを行ごとに解読する
まずは curl から始めましょう。curl はあなたと HTTP リクエストの間の抽象化をすべて取り除くため、何か問題が起きたときに、問題がクライアントライブラリではなくリクエスト側にあると特定できます。
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "シーンを柔らかな水彩イラストに変え、被写体と構図は維持する",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
以下で各部分の役割を順に説明します。
リクエスト行
-X POST はメソッドを設定します。URL は HiAPI API のベースアドレスに画像生成パスを加えたものです。ベースアドレスは変数や設定値に置いて、複数箇所でのハードコードを避けるべきです。そうすれば将来の変更は 1 箇所を編集するだけで済みます。
ヘッダー
Authorization: Bearer $HIAPI_API_KEY は認証情報を運びます。シェルが先ほどエクスポートした環境変数を展開するため、キーがコマンド履歴にそのままの形で残ることはありません。Content-Type: application/json は、リクエストボディを JSON として解析するよう API に伝えます。JSON ボディを送るのにもかかわらずこのヘッダーを欠かすことは、わかりにくいエラーを招くよくある原因です。
ペイロード
model は fibo-2.0/image-to-image を識別します。prompt はあなたの指示です。入力画像がすでに構造を担っているため、出力画像全体ではなく編集内容を記述してください。image はインターフェースが受け付ける入力画像の形式です。直接埋め込む場合は、ファイル内容を base64 でエンコードしたものです。n は要求する出力数を制御し、デフォルトのままが最も安全な出発点です。
画像が大きい場合、シェルコマンドへの直接埋め込みは扱いにくくなります。先にファイルへエンコードしてそれを参照するか、あるいは次のセクションの Python 方式に切り替えてください。そこではファイルを読み込んでエンコードするのに 1 行で済みます。
レスポンスの読み取り
レスポンスに完成した画像バイトが含まれていると仮定してはいけません。curl 呼び出しを実行して JSON を確認してください。探すべきはジョブ識別子またはステータスフィールドで、タスクが完了しているかまだ実行中かを判断します。解析コードを書く前にまず構造を捕捉してください。レスポンスの形がポーリング方法を決めるからです。
リクエストを Python へ移植する
Python を使えばリクエストは保守しやすくなり、コードベース全体で再利用できる関数としてカプセル化できます。以下は同じリクエストを実装した軽量クライアントです:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
なぜこの構造なのか
encode_image と submit_image_edit を分離することで、ファイル処理と HTTP 処理が互いに独立し、それぞれテストしやすくなります。インポート時に環境からキーを読み込めば、数層先で 401 が発生するのではなく、キーが欠けている時点で即座に失敗します。timeout を明示的に設定すれば、接続の停滞によってワーカープロセスが無限にハングするのを防げます。
レスポンスボディの扱い
raise_for_status() は HTTP 層の失敗を、レスポンスボディのログを添えて捕捉できる例外に変換します。これはエラーオブジェクトを黙って成功として解析するよりもはるかに有用です。解析済みの JSON を取得したら、そこに含まれるジョブ識別子を記録し、開発中はレスポンス全体を記録して、実際にどんなフィールドがあるのかを把握してください。仮定に基づいてパーサーを書くのではなく、実際に観察したレスポンスに基づいて書いてください。
再利用性を保つ
2 つの小さな改善がすぐに報われます。ベース URL とモデル名を定数に置き、他のモデル呼び出しがそのクライアントを共有できるようにすること。そして送信関数が型付けされた構造(小さな dataclass か、既知のキーを持つ dict)を返すようにし、ポーリングコードが依存できる安定した契約を持てるようにすることです。
非同期ライフサイクルとポーリングの処理
画像ジョブは一瞬では完了しません。統合では送信と完了を 2 つの独立したイベントとして扱うべきです。
ステップ 1:送信して永続化する
ジョブを送信したら、ジョブ識別子を永続的な場所に保存します。データベースの行、キューメッセージ、あるいは少なくとも 1 行のログです。送信と完了の間でプロセスがクラッシュした場合、記録されていないジョブは失われた作業です。識別子を、あなたのシステム内でその結果を所有するエンティティに結びつけておき、後で照合できるようにしてください。
ステップ 2:バックオフ付きのポーリング
妥当な間隔でジョブ状態のインターフェースをポーリングします。タイトなループで状態インターフェースを叩き続けるのはリソースの無駄であり、最もよくある非同期の誤りです:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
短い間隔から始めて徐々に伸ばすことで、初期のチェックの応答性を保ちつつ、長期的な高頻度リクエストを避けられます。厳格な締め切りを設けることで、決して完了しないジョブを無限に待つことを防ぎます。
ステップ 3:失敗を通常の結果として扱う
完了したジョブが必ずしも成功したジョブとは限りません。出力を読む前にステータスを確認し、失敗を明示的に分岐処理してください。ジョブが返すエラー詳細を記録し、呼び出し元にリトライ可能のシグナルを出し、リトライ時に同じ入力を再利用するか再生成するかを決めます。クライアント側でタイムアウトしたジョブはサーバー側でまだ実行中かもしれません。ですから確認せずに盲目的に再送信してはいけません。
ステップ 4:結果を取得して保存する
ジョブが成功を報告したら、提供された出力参照を読み取り、速やかにダウンロードします。結果を長期的に保存する場合は、参照が永久に有効であることに頼らず、自分のストレージへコピーしてください。
よくあるエラーと修正方法
ほとんどの失敗は予測可能ないくつかのカテゴリに分類できます。このチェックリストを順に確認してください。
認証の失敗
401 や 403 は、ほぼ常にヘッダーの誤りかキーの欠落を意味します。ヘッダーが厳密に Authorization: Bearer <key> であり、Bearer の後に半角スペースが 1 つあることを確認してください。また、環境変数がリクエストを発行するプロセスに実際に設定されていることを確認してください。インタラクティブシェルにだけ設定されていては不十分です。キーを貼り付ける際の末尾の空白や余分な引用符は、この種の問題のかなりの割合を占めます。
ペイロード形式の誤り
400 や 422 は通常、API がリクエストボディを解釈できないことを意味します。次の 3 つを順に確認してください。Content-Type: application/json が存在するか、JSON が実際に解析できるか(末尾のカンマはこれを壊します)、必須フィールドが正しい名前で存在するか。base64 の画像データを送る場合は、それが正当な base64 であり、基になるファイル形式がサポートされていることを確認してください。切り詰められた文字列や二重エンコードされた文字列は、不可解な検証エラーを生みます。
ポーリングの誤り
ジョブが決して完了しないように見える場合、ポーリングに送信レスポンスが実際に返した識別子を使っているか、正しいステータスフィールドを読んでいるかを確認してください。failed ステータスを無視するタイトなループは、ハングしているように見えます。厳格なタイムアウトを設け、観察された状態変化を記録してください。そのログは通常、問題を即座に明らかにします。
レスポンス解析の落とし穴
結果を読むときにコードが例外を投げるなら、レスポンスの形を推測してはいけません。まず生のレスポンスボディを記録してください。よくある問題には、参照をバイトと取り違えること、成功時のみ存在するフィールドを常に存在するとみなすこと、失敗パスのパーサーで成功レスポンスを解析することが含まれます。実際に見たことのあるレスポンスに基づいて抽出ロジックを構築してください。
迅速なトリアージの習慣
問題が起きたら、まず層を切り分けます。同じペイロードで curl コマンドを実行してください。curl が成功して Python が失敗するなら、誤りはクライアント側です。両方とも失敗するなら、誤りはリクエスト側です。この単純なテストは、他のどんなデバッグ習慣よりも時間を節約します。
動作する呼び出しと堅牢なポーリングループがあれば、fibo-2.0/image-to-image は信頼できる編集ステップになります。HiAPI のモデルページから始めて、上記のリクエストをあなた自身の画像に適合させてください。