チュートリアル
HiAPI API で fibo-2.0/text-to-image を呼び出す方法:curl と Python の実践
このページの内容
本チュートリアルで構築するもの
これは、HiAPI 上の fibo-2.0/text-to-image から実際に画像を取得するまでのハンズオン実践ガイドです。終わる頃には、すぐに実行できる2つのものが手に入ります。有効な画像生成リクエストを生成する curl コマンドと、同じことを行い、後続処理のために結果を返す小さな Python 関数です。
私たちは、ほとんどの開発者が実際に作業する順序で進めます。まず、環境と認証情報が整っていることを確認します。次に、リクエストボディをフィールドごとに読み、各部分が何を制御するのかを明確にします。続いて curl で呼び出しを送り、エンドポイント、キー、リクエストペイロードの3つが一致していることを証明します。それが済んで初めて、同じリクエストを Python に移植します。そこから、本当に興味深い作業——レスポンスの解析、失敗の処理、関数へのカプセル化——が始まります。
目標は、考えられるすべてのパラメータを列挙することではなく、完全に理解できるリクエストの形を提供し、推測なしにプロンプト、出力サイズ、周辺コードを自分のユースケースに合わせて調整できるようにすることです。
最初のリクエストを送る前に
最初の呼び出しを成功させるには、3つの条件を満たす必要があります。
HiAPI アカウントと API キー
fibo-2.0/text-to-image へのリクエストには認証が必要です。HiAPI アカウントで API キーを生成し、ソースコード管理から遠ざけてください。以下の例では、キーをハードコードせず環境変数から読み取ります。後からキー処理を追加するのは面倒なので、初日からそうしてください。
export HIAPI_API_KEY="your-api-key-here"
HTTP リクエストを送信できるツール
curl 実践パートでは、マシンに curl が必要です。macOS とほとんどの Linux ディストリビューションには同梱されています。Windows では、現在のバージョンおよび Windows Terminal でも利用できます。Python パートでは、Python 3 と requests ライブラリが必要です。これはスクリプトから HTTP 呼び出しを行う最も一般的な方法です。まだインストールしていない場合:
pip install requests
何を生成したいかを明確にする
プロンプトを用意してください。画像モデルは、具体的で明確な記述——被写体、スタイル、ライティング、構図——に強く反応するので、通常は一行のアイデアでテストを始めるのに十分です。最初の結果を見たら、それをさらに最適化し続けるでしょう。これは正常なサイクルです。
この3つが整えば、あとはすべてリクエストボディに関する話です。
リクエストをフィールドごとに解析する
fibo-2.0/text-to-image の呼び出しは、JSON リクエストボディを伴う POST リクエストです。リクエストボディは小さく、プロンプトと出力を形作る設定だけです。完全なペイロードを暗記するのではなく、各フィールドを理解して、意識的に変更できるようにしましょう。
モデル識別子
エンドポイントのパス自体がモデルを示しています:fibo-2.0/text-to-image。ほとんどの場合、追加でモデル文字列を渡す必要はありません。呼び出すルートが、実行するモデルを決定します。統合が共有エンドポイント経由のルーティングをサポートしている場合は、モデル名を設定定数に入れておけば、呼び出し箇所を変更せずに切り替えられます。
プロンプト
これが中心的な入力です。欲しい画像のテキスト記述です。願望ではなく仕様書として扱ってください。抽象的な概念よりも、被写体、視覚スタイル、構図を述べる方が、モデルに多くの有用な情報を与えられます。プロンプトは変数や別ファイルに入れておけば、リクエストコードを書き直さずに素早く反復できます。
出力設定
画像リクエストは通常、少数の出力制御項目を持ちます。最も一般的なのは、生成画像のサイズまたはアスペクト比、そして複数の結果が欲しい場合の枚数です。HiAPI モデルリファレンスで fibo-2.0/text-to-image 用に文書化されているフィールド名を使用してください。以下のサンプルペイロードはそれらの正式名称を使用しています。ある設定がそのモデル用に文書化されていない場合は、推測せずに省略してください。未知のフィールドは検証エラーのよくある原因です。
リクエストボディに入れないもの
API キーを JSON リクエストボディに入れないでください。認証はリクエストヘッダーに属します。認証情報をペイロードから遠ざけておけば、リクエストボディをデバッグ時に安全に記録・比較できます。最初のリクエストが失敗したときにそのありがたみがわかるでしょう。
動作する curl リクエスト
以下は完全な呼び出しです。自分のプロンプトに置き換え、HIAPI_API_KEY が設定されたシェルで実行してください。
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "夜明けの静かな港、水面にたなびく薄い霧、ワイド構図、写真スタイル",
"size": "1024x1024",
"n": 1
}'
各部分の役割
-X POSTは HTTP メソッドを設定します。画像生成は作成操作なので、GET ではなく POST です。- URL は HiAPI API ホスト上の
fibo-2.0/text-to-imageルートを指します。アカウントがリージョン別またはプロジェクト専用のベース URL を使用している場合は、そのホストに置き換えてパスを保持してください。 Authorization: Bearer $HIAPI_API_KEYは環境からキーを渡します。シェルが変数を展開するので、キーがリテラル文字列としてコマンド履歴に残ることはありません。Content-Type: application/jsonは、リクエストボディが JSON であることをサーバーに伝えます。これがないと、多くのゲートウェイはリクエストがモデルに届く前に拒否します。-d '...'は JSON リクエストボディです。プロンプト、要求サイズ、画像1枚の枚数です。
結果を検証する
コマンドを実行し、まず生の出力を見てください。成功した呼び出しは生成画像を記述した JSON ドキュメントを返し、失敗した呼び出しはエラーオブジェクトを返します。この上に何かを構築する前に、目視で両者を区別できることを確認してください。レスポンスが大きい場合は、jq などの整形ツールで処理して構造を読みやすくします:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"夜明けの静かな港","size":"1024x1024","n":1}' | jq .
手動の呼び出しが成功すれば、認証情報とペイロードが容疑者から外れます。それ以降の問題はすべてあなたのコードの中にあります。
Python での同じ呼び出し
Python 版はシェルコマンドが行うこととまったく同じですが、入力を検証し、リトライし、結果を保存する場所を提供します。小さく明確に保ちましょう。
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"夜明けの静かな港、水面にたなびく薄い霧、ワイド構図、写真スタイル"
)
print(result)
なぜこのように書くのか
- キーは関数内部で環境から読み取るため、存在しない場合は起動時に大きな失敗となり、未認証のリクエストを送ることはありません。
json=payloadにより、requestsがリクエストボディをシリアライズし、コンテンツタイプを正しく設定します。Python で JSON 文字列を手作りしないでください。実行時まで発見できない引用符の誤りを招きます。timeout=60は、遅い失敗を明確にします。画像生成は瞬時ではないので、待ってもよいタイムアウトを選んでください。ただし必ず設定してください。raise_for_status()は 4xx および 5xx レスポンスを例外に変えます。この一行が、失敗した呼び出しが黙って成功として扱われるのを防ぎます。- 関数は
prompt、size、nを引数に取るので、プログラムの残りの部分から他のライブラリ関数と同じように呼び出せます。
ファイルを実行すると、curl 呼び出しが返したのと同じ JSON 構造が表示されるはずです。
レスポンスの読み取りとエラー処理
成功したレスポンスは、生成された出力を記述した JSON オブジェクトを返します。関心のある詳細は生成画像そのもの——通常はダウンロードまたは保存できる URL や参照——と、API が返すリクエストに関するメタデータです。レスポンスはデータとして解析してください。文字列操作で攫い取らないでください。初めてライブレスポンスを確認したときに形が期待と違う場合は、パーサーを調整する前にモデルリファレンスを確認してください。フィールド名を推測することが、統合が静かに壊れる原因です。
失敗の検出
意図的に処理する価値のある失敗には3つの層があります。
転送エラー。 リクエストが完了しませんでした:DNS 失敗、接続リセット、タイムアウト。Python ではこれらは requests.exceptions として現れ、バックオフ付きで安全にリトライできます。
HTTP エラーステータス。 サーバーは応答しましたが、リクエストを拒否しました。401 は通常、キーが欠落しているか誤っていることを意味します。4xx の検証エラーは通常、フィールド名または値が間違っていることを意味します。429 は送信が速すぎることを意味します。5xx はサーバー側で問題が発生したことを意味します。raise_for_status() はこれらすべてを1つの例外として捕捉するので、何をするかを決める前にレスポンスボディのメッセージを確認してください。
ステータスコード 200 だが予期しないレスポンスボディ。 これが、構造を仮定せず検証する理由です。使用する前に依存するフィールドが存在するか確認し、ステータスコードが 200 でも画像参照の欠落を失敗とみなしてください。
try:
result = generate_image("夜明けの静かな港")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
重要な習慣:エラーを黙って飲み込まないこと。少なくともステータスコードとレスポンスボディを記録してください。このペアが、ペイロードを修正すべきか、待ってリトライすべきかを教えてくれます。
本番環境へ向けて
単一の呼び出しが動作し、失敗が見えるようになったら、いくつかの小さな習慣で、実際のトラフィック下でも統合が持ちこたえられるようになります。
安全にリトライできるものだけをリトライする
転送エラー、タイムアウト、429 および 5xx レスポンスは、指数バックオフと試行回数の上限を設けてリトライする価値があります。検証エラーと 401 はそうではありません。不正な形式のリクエストをリトライしてもクォータを消費するだけです。エラー処理でこの2種類を明確に区別してください。
設定をコードから遠ざける
API ベース URL、モデルパス、デフォルトサイズ、タイムアウトは、関数内に散らばせるのではなく設定に置いてください。テスト環境から別の環境に移行するとき、または後で同種のモデルを試すときに、1か所を変更するだけで済みます。
リクエストとレスポンスを記録するが、キーは除く
プロンプト、パラメータ、ステータスコード、切り詰めたレスポンスを記録してください。API キーは絶対に記録しないでください。これにより、1週間後に「なぜこの画像が正しく返ってこなかったのか」を再現せずに答えられます。
送信前に入力を検証する
プロンプトが空でなく、妥当な長さであることを確認し、size と n がモデルの文書化された値と一致することを確認してください。誤った値をローカルで捕捉する方が、往復するより速く安価です。
結果は印刷するだけでなく保存する
生成された画像参照は一時的な場合があります。同じジョブの一部として、出力を自分のストレージにダウンロードまたはコピーし、どのプロンプトとパラメータがそれを生成したかを記録してください。その記録が再生成と監査を可能にします。
fibo-2.0/text-to-image を本チュートリアルの小さな generate_image 関数の背後にカプセル化し、アプリの残りの部分が生の HTTP 呼び出しではなくその関数に依存するようにしてください。プロンプトを大規模に変化させる準備ができたら、HiAPI モデルリファレンスが、インターフェースを拡張する前にサポートされるパラメータを確認する場所です。