チュートリアル
HiAPI API を使って flux-3 を利用する方法:curl、Python、実行可能なリクエスト例
このページの内容
HiAPI 経由で flux-3 を使うと何が得られるか
flux-3 は画像生成モデルであり、テキストからの画像生成も画像からの画像生成も扱えます。プロダクト機能やデザインツール、社内パイプラインを構築している場合、本当に興味深いのはモデルそのものではなく、それをどれだけきれいに安定した予測可能なインターフェースの背後に置き、要件が変化してもその状態を保てるかという点であることが多いです。
そこにこそ集約型 API プラットフォームの価値があります。HiAPI 経由で flux-3 を呼び出すということは、次のことを意味します。
- 統合は一度だけ。 単一のベース URL、単一の認証方式、そして利用するモデル間で一貫したリクエスト・レスポンス構造。後からモデルを差し替えたり比較したりするのは、コードを書き直すのではなく設定を変えるだけです。
- インフラ作業が不要。 モデルのホスティング、GPU 容量の計画、コールドスタートの管理を自分の側で行う必要はありません。HTTP リクエストを送り、レスポンスを処理するだけです。
- 認証情報を一元管理。 発行・ローテーション・権限スコープを設定する API キーは 1 つだけで済み、上流プロバイダーごとに個別の関係を築く必要はありません。
- 統一されたエラーセマンティクス。 呼び出しの背後がどのモデルであっても、ステータスコードとエラーラッピングが同じなので、リトライやアラートのロジックを再利用できます。
flux-3 に限って言えば、notebook 上のプロトタイプから本番エンドポイントへ、クライアントコードの構造を変えずにそのまま移行できます。2 つの生成モード——テキスト生成と画像生成——は同じリクエスト構造を共有しているため、両方に対応できるかどうかは、どの SDK をインポートするかではなく、どのフィールドを埋めるかで決まります。
本記事では以下の前提で進めます。
- ベース URL: アカウントのコンソールに記載された HiAPI API エンドポイント。
- 認証:
Authorizationヘッダーで bearer トークンを渡します。 - コンテンツタイプ: リクエストボディは
application/json、画像入力はペイロードサイズの制限に応じて URL または base64 エンコードデータで提供します。
キーは環境変数に置き、ソース管理にコミットしないでください。以下の例ではキーを HIAPI_API_KEY から、モデル識別子を FLUX_MODEL から読み込むため、コードを変更せずに切り替えられます。
前置きはこれくらいにして、次の節ではリクエストボディ自体を分解します。
リクエスト構造の解剖:テキスト生成と画像生成
flux-3 の呼び出しは論理的に 3 つの部分に分かれます。エンドポイントパス、認証ヘッダー、そして JSON リクエストボディです。リクエストボディが 2 つのモードで異なる部分であり、この違いを理解すれば 1 つのクライアントを両方に再利用できます。
共通の骨格
すべてのリクエストには、何らかの形で以下のフィールドが含まれます。
- model — 呼び出すモデル。ここではあなたの flux-3 識別子です。
- input — 生成指示を格納するオブジェクト。
- input.prompt — 欲しいものを自然言語で記述します。どちらのモードでも必須です。
- オプションの生成設定 — 出力サイズ、アスペクト比、ステップ数など、モデルが公開する機能に依存します。必要なものだけを設定してください。通常、デフォルト値で十分に妥当です。
- オプションの非同期制御 — タスクの実行と配信方法を変えるフラグやコールバック(次の節で詳述)。
テキストからの画像生成
テキストからの画像生成モードでは、prompt が唯一の実質的なフィールドです。画像を記述し、必要に応じて出力のジオメトリを制約してから送信します。元画像がないため、モデルには最大限の自由度があり、それはすなわちプロンプトの品質が出力品質を支配するということです。
有用な習慣として、人間のイラストレーターに依頼するようにプロンプトを書いてください。被写体、構図、ライティング、スタイル、そして「画像内に文字を入れない」「被写体を中央に」といったハード制約の順に書きます。曖昧なプロンプトは、ステップ数をいくら増やしても平凡な結果しか生みません。
画像からの画像生成
画像からの画像生成モードでは、プロンプトに加えて元画像フィールドを追加します。このときプロンプトは、ゼロから構築するシーンではなく、その入力に対する変換を記述するものになります。モデルのインターフェースによっては、画像 URL またはエンコードされた画像ペイロードを提供し、さらに出力が元画像からどの程度逸脱するかを制御する強度やガイダンスのパラメータを加えることを意味します。
API クライアントにとって実際の影響は小さいです。同じエンドポイント、同じ認証、同じ input オブジェクトで、フィールドが 1 つ増えるだけです。これこそが設計目標です。generate() 関数はオプションの元画像を受け取り、内部で分岐を処理するようにすれば、呼び出し側は自分がどちらのモードを起動したかを知る必要がありません。
レスポンス構造
レスポンスにはタスク識別子が含まれ、完了時には生成画像の場所が含まれます。その場所は不透明な値として扱ってください。取得や保存はできますが、その内容について解析上の仮定を置かないでください。即時返却されるレスポンスもあれば、タスクハンドルを返すものもあり、だからこそ非同期処理を初日から設計に組み込む必要があります。
パラメータと非同期モード
生成設定の選択
生成設定は品質、レイテンシ、コストの間のトレードオフです。以下の原則は flux-3 を含むほとんどの画像モデルに当てはまります。
- 解像度とアスペクト比 は出力の実用性と計算コストの両方に影響します。実際に届けるサイズで生成してください。大きな画像を縮小するのは予算の無駄であり、小さな画像を拡大するのはレンダリングの無駄です。
- ステップ数や品質制御 は、ある点を過ぎると忠実度の向上が頭打ちになります。固定プロンプトで実測してこの変曲点を見つけ、そこで止めてください。
- 決定性の制御(利用可能な場合)は再現性に重要です。QA やユーザーサポートのために同じ結果を再レンダリングする必要があるなら、設定を出力と一緒に記録してください。
パラメータ名や許容範囲を推測しないでください。コンソール内のモデルドキュメントから読み取り、それに従ってください。あるフィールドが拒否された場合、エラーレスポンスがどれかを正確に教えてくれます。
同期 vs. 非同期
画像生成は即時操作ではありません。実行モードは 2 つあります。
同期(ブロッキング)。 リクエストを送信し、画像が準備できるまで接続を保持します。シンプルで、短いタスク、スクリプト、ユーザーがローディングアニメーションを見つめるインタラクティブツールに適しています。しかし脆くもあります。サーバーレス関数、ロードバランサー、モバイルクライアントにはタイムアウト制限があり、長時間のレンダリングは必ずそのいずれかにぶつかります。
非同期(タスクベース)。 リクエストを送信するとすぐに識別子を受け取り、その後ステータスエンドポイントのポーリングまたはコールバックの受信によって、タスクが完了を報告するまで待ちます。以下のような場合はこのモードを選ぶべきです。
- 厳しい実行時間上限があるサーバーレスやエッジランタイム。
- 多数のレンダリングを並行して送信するバッチ処理。
- すぐに制御を戻し、進捗をストリーミングで届けたいあらゆるユーザーインタラクションフロー。
クライアントは非同期を中心に設計し、単純なケースは同期の便利メソッドで包んでください。逆——非同期をブロッキングクライアントに無理やり詰め込む——はほとんど良い結果になりません。
ポーリングする際は、固定のタイトループではなく上限付き指数バックオフを使い、総待機時間に上限を設け、永遠に終態に到達しないタスクはアラートに値するエラーとして扱ってください。
実行可能な curl リクエスト
ターミナルから始めましょう。生の HTTP 交換が明確になれば、コード版は簡単です。
1. 環境の設定
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
モデル識別子は変数に入れておきましょう。後でモデルを変えるときは 1 行変えるだけです。
2. テキストからの画像生成リクエストを送信
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
}
}'
-sS フラグは出力をクリーンに保ちつつ、エラーは表示し続けます。実行前に、コンソールに記載されたエンドポイントと正確なパスを確認してください。パスにはバージョンが付くため、ドキュメントに従ってください。
3. 返却内容の読み取り
レスポンスをフォーマッタに通して読みやすくします。
... | python -m json.tool
注目すべきは 2 点です。タスク識別子と、画像の場所、またはタスクがまだ実行中であることを示すステータスフィールドです。画像ではなくステータスが見えたなら、あなたは非同期パス上にいます。識別子をメモしてポーリングに移ってください。
4. 画像からの画像生成を試す
元画像を input オブジェクトに追加し、それ以外はそのままにします。
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
"image": "https://example.com/source.jpg"
}
}'
リクエストはフィールド 1 つ分しか違わないため、最初の成功呼び出しで統合の大部分はすでに検証済みです。残り——リトライ、保存、UI——は通常のアプリケーション作業です。
Python での同じリクエスト
curl 呼び出しはそのまま翻訳できます。以下は使い捨てスクリプトではなく、小さく再利用可能なクライアントです。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Submit a flux-3 generation job. Pass image= for image-to-image."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
意図的な選択がいくつかあります。
- 1 つの関数、2 つのモード。
image引数が動作を切り替えるため、呼び出し側は分岐不要です。 - 明示的なタイムアウト。
requestsのデフォルト動作——無限待機——は、ワーカースレッドプールを壊すまさにその方法です。 raise_for_status()。 HTTP 層の失敗を例外として表面化させ、1 か所で捕捉できます。
ポーリングヘルパーの追加
レスポンスが完成した画像ではなくタスク識別子を返す場合、それを待ちます。
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
ステータスフィールド名は、ドキュメントに記載されたレスポンス構造に合わせて調整してください。構造そのもの——上限付きバックオフ、ハードな締め切り、終態チェック——が鍵であり、モデルを変えてもそのまま通用します。
組み合わせる
if __name__ == "__main__":
result = generate(
"A minimal studio photograph of a ceramic mug, soft side light"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
次に、generate を独自のリトライとログの層で包めば、統合は本番形態を備えたことになります。
コスト管理とよくあるエラー
支出を予測可能に保つ
画像生成はリクエスト単位で課金され、具体的な金額はモデルと設定に依存します。思い込みをハードコードせず、コンソールのリアルタイム価格パネルを確認してください。予算を守る鍵はエンジニアリングの規律です。
- 自分のコードでユーザーごと・タスクごとの上限を設ける。 プラットフォームはアカウントレベルの制限を適用しますが、アプリケーションはプロダクトレベルの制限を適用すべきです。そうすれば 1 つの暴走したクライアントがアカウント全体を枯渇させることはありません。
- 積極的にキャッシュする。 正規化したプロンプトと設定をハッシュ化し、保存済みの出力を再利用します。エディタやプレビューのシナリオでは同じリクエストが頻繁に発生します。
- 納品する解像度で生成する。 表示するサイズでレンダリングし、「大きな画像でレンダリングしてから縮小する」という高コストなパターンを避けてください。
- 再生成は明示的なユーザー操作の後に行う。 プロンプト入力欄でキーを叩くたびに自動再生成するのは、最もよくある予期せぬコスト倍増要因です。
- 呼び出しごとにモデル、設定、レイテンシを記録する。 これらがなければ、どの機能が高コストかを判断できません。
- 送信前に入力を検証する。 空のプロンプトや異常に長いプロンプトをクライアント側で拒否すれば、必ず失敗するリクエストに料金を払うことは決してありません。
実際に遭遇する障害のデバッグ
以下のチェックリストを順に確認してください。ほとんどのインシデントはこれで解決します。
- 401 / 403 — 認証。 キーはリクエストが実際に実行される環境に読み込まれていますか? シェルで使えるキーがコンテナには存在しないことがあります。
Bearerプレフィックスとヘッダー名が完全に正しいことを確認してください。 - 404 — パスまたはモデルの誤り。 バージョン付きパスとモデル識別子はどちらも変化します。ドキュメントに記載されたエンドポイントと 1 文字ずつ照合してください。
- 422 / 400 — ペイロードが拒否された。 エラーボディが問題のフィールドを指し示します。よくある容疑者は、型の誤り、
promptの欠落、サポートされないパラメータです。オプション設定を外して再送信し、問題を切り分けてください。 - 429 — レート制限に達した。 ジッター付きでバックオフしてリトライし、ループ内で即座に再試行しないでください。アカウントレベルのクォータ枯渇とは区別してください。後者はリトライしても無駄です。
- タイムアウト。 リクエストに時間がかかりすぎるなら、ポーリングすべきところでブロッキングしています。非同期フローに切り替え、クライアントのタイムアウトを意識的に設定してください。
- タスクが pending のまま。 締め切り付きでポーリングし、タイムアウトは無限待機ではなくアラート対象の失敗として扱ってください。
チェックリスト全体をつなぐ習慣が 1 つあります。ステータスコードだけでなく、エラーボディ全体を記録することです。エラーボディは通常、どのフィールドまたは制限が問題かを正確に教えてくれるため、30 分の調査が 1 行の修正になります。
まず curl 呼び出しを通し、上記のクライアントへ移植し、ポーリングとエラー処理を 1 か所に集中させてください。残りの統合は通常のアプリケーションコードです。現在のモデル機能と価格については、HiAPI コンソールの flux-3 ドキュメントと価格パネルを参照してください。