チュートリアル
HiAPI 経由で fibo-gen-1.5/text-to-image を呼び出す方法:curl と Python ガイド
このページの内容
curl で動作するリクエストを構築する
fibo-gen-1.5/text-to-image は、標準的な HiAPI リクエストパターンでアクセスするホスト型テキスト画像生成モデルです。この点は一見した以上に重要です。重みをダウンロードしたり、GPU を用意したり、モデル専用の SDK を学ぶ必要はありません。モデル識別子とプロンプトを含む HTTP リクエストを送信し、画像の結果を受け取るだけです。統合作業は三か所に集中します——プロンプトをどう設計するか、どのパラメータを設定するか、そしてレスポンスをどう処理するかです。
コードを書く前に、安心して前提としてよいことがいくつかあります:
- 認証方式は統一されています。 すべての HiAPI 呼び出しはリクエストヘッダに API キーを含めます。モデルごとの認証フローは存在しません。
- モデルは名前で選択します。
fibo-gen-1.5/text-to-imageをモデルフィールドとしてリクエストボディに含め、/text-to-imageサフィックスを含めてそのまま記述する必要があります。 - 呼び出し側から見ると生成は同期的です。 リクエストを送信し、待機し、出力を受け取ります。タイムアウトの予算は即時返却を仮定するのではなく、実際の生成遅延を反映すべきです。
- レスポンスは構造化されています。 生のバイナリデータブロックではなく JSON のラッパーを受け取るため、画像を使用する前にまず解析が必要です。
すでに他の HiAPI モデルを統合したことがあるなら、これは馴染み深く感じられるでしょう。これが初めてなら、ここで学ぶパターンはプラットフォーム上の他のすべてにそのまま応用できます。本当にモデル固有の知識はパラメータ選択にあり、本ガイドの後半で説明します。
Python で同じ呼び出しを実行する
成功する最小限の呼び出しから始めましょう。キーをエクスポートして、シェル履歴に平文で残らないようにします:
export HIAPI_API_KEY="your_api_key_here"
次にリクエストを送信します:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-gen-1.5/text-to-image",
"prompt": "夜明けの木製桟橋で網を繕う朽ちた漁師、曇り空の光、35mm 写真",
"size": "1024x1024",
"n": 1
}'
特に指摘すべき点が三つあります。これらは「コピー&ペーストで運任せ」の試みが通常失敗する箇所だからです:
- モデル文字列は正確でなければなりません。
fibo-gen-1.5/text-to-image——fibo-gen-1.5でも大文字小文字の変種でもありません。少しでもずれるとモデル未検出系のエラーが返り、静かにフォールバックすることはありません。 - キーは bearer トークンとして
Authorizationヘッダに入れます。 リクエストボディやクエリ文字列に入れないでください。 Content-Type: application/jsonは必須です。 これがないと、一部のプロキシやゲートウェイがペイロードを API に到達する前に壊してしまうことがあります。
正確な返却内容——レスポンスヘッダを含めて——を確認したい場合は、curl 呼び出しに -i を加えます。レスポンスが空に見えるときに最も役立つデバッグ習慣です:200 だがレスポンスボディの形状が異常なのか、それとも処理すべき非 2xx ステータスなのかがわかります。探索時には jq . をパイプして JSON を整形出力できます。
成功したら、プロンプトを変えて再実行します。呼び出しの残りをそのままにしておくことで、プロンプトの変更と構造の変更を切り離せます。
本番環境へ投入する
動作するスクリプトから信頼できる統合へ進むには、主に地味な部分が重要になります。チェックリスト:
- キーをコードに入れない。 環境変数やシークレットマネージャから読み込み、絶対にコミットせず、実際に守れる周期でローテーションします。開発と本番で別のキーを使えば、開発キーの漏洩が本番トラフィックを止めることはありません。
- タイムアウトは明示的かつ根拠を持つ。 推測ではなく、自身のワークロードで観測した生成遅延に基づいて上限を設定します。この数値の根拠とするために、各呼び出しの実測所要時間を記録します。
- リトライは上限付きで選択的に。 一時的な障害——タイムアウト、レート制限の状況——には指数バックオフと厳格な試行上限でリトライします。不正なペイロードや認証失敗は絶対にリトライしないでください。毎回同じように失敗し、クォータを浪費するだけです。
- 出力は信頼する前に検証する。 デコードしたバイト数が妥当な量に達しているか、ファイルが有効な画像として開けるかを確認します。CDN に届くゼロバイトや切り詰められたファイルは、生成段階で直接エラーになるより悪いです。
- すべての生成を記録する。 プロンプト、パラメータ、レスポンス、タイムスタンプをまとめて保存します。これにより後日、再現性とコスト配分が可能になります。
- 呼び出しはあちこちに散らさず関数の背後にまとめる。 単一の
generate()を統一的に使えば、リトライロジック、タイムアウト、ログ記録を一か所で修正できます。
まず curl でクリーンな fibo-gen-1.5/text-to-image リクエストを送信し、次に Python へ移植し、その後その周りに運用レイヤーを追加します。リクエストの形状は常に変わらず——変わるのはそれを包む保障だけです。