HiAPI
ブログ

チュートリアル

HiAPI API で flux-3-image-klein を呼び出す方法:curl、Python、および利用可能なリクエスト例

開発者向けの統合実践:最初のリクエストから信頼性の高いバッチ呼び出しまで

Nov 12, 2026
ほぼ黒色のカバー画像で、ミントグリーンの点のフィールドが左から右へ密度を増しながら広がり、端からはティール色の点がこぼれ出ている。
モデル
flux-3-image-klein
このページの内容

flux-3-image-klein 統合の実際の要件

最初のコードを書く前に、スクリプトと生成画像の間に一体いくつの要素が挟まっているかを把握しておきましょう。HiAPI 上の flux-3-image-klein の場合、そのリストは短いものです:エンドポイント1つ、認証情報1つ、JSON リクエストボディ1つ、そして解析すべきレスポンスオブジェクト1つです。

頭に入れておくべきメンタルモデルは次のとおりです:

  • エンドポイント — 1本の HiAPI ルートがこのモデルの画像生成を処理します。すべてのリクエストはそこに送られ、モデルは異なる URL で区別されるのではなく、リクエストボディ内で識別されます。
  • 認証情報 — HiAPI アカウントから発行される API key です。呼び出しごとに HTTP ヘッダーで渡します。パスワードと同様に扱い、環境変数から読み取り、コミットされうるファイルにハードコードしないでください。
  • リクエストボディ — モデル、プロンプト、および出力に影響する少数の任意パラメータ(サイズ、スタイル関連のヒントなど)を記述した小さな JSON オブジェクトです。
  • レスポンス — 生成画像への参照と API が付随して返すメタデータを取得するために解析する JSON オブジェクトです。

開始前に確認する価値のある前提条件が2つあります。第一に、キーが有効で画像生成権限を持っていることを確認してください。あるモダリティに有効なキーが別のモダリティにも自動的に有効とは限りません。第二に、現在の HiAPI ドキュメントをタブで開いておいてください。パラメータ名、サポートされるサイズ、レスポンスフィールドは変わりうるため、記憶やあるブログ記事(本記事を含む)ではなく、ドキュメントこそが照合すべき唯一の真実の情報源です。

本ガイドの残りでは、リクエストを構築し、Python に移植し、実際の負荷に備えて堅牢化します。順番に従えば、各ステップは前のステップを再利用し、途中で学び直すものはありません。

curl で最初の動作するリクエストを送る

統合が動作するかを確認する最速の方法は、シェルで curl 呼び出しを1回送ることです。ここで成功レスポンスが得られれば、後はすべてパッケージングに過ぎません。

まずキーをエクスポートし、シェル履歴にリテラルとして残らないようにします:

export HIAPI_API_KEY="your-api-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

次に最小限のリクエストを送信します:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image-klein",
    "prompt": "夕暮れの崖の上に建つ風化した灯台、長露光、柔らかな霧"
  }'

URL に関する注意:正確な base path とルートは HiAPI ドキュメントで定義されています。サードパーティのスクリーンショットからホスト名をコピーするのではなく、ドキュメントのエンドポイントを使用してください。環境に HIAPI_BASE_URL を一度設定すれば、以降のすべての例で再利用できます。

ここで各フィールドの役割を見てみましょう:

  • model はどのモデルがタスクを処理するかを識別します。ドキュメントと完全に一致させてください。ここでのタイポは、リクエストが一見正当に見えても有用な結果が返らない最も一般的な原因です。
  • prompt は自然言語による記述です。被写体、構図、光、雰囲気を具体的に説明してください。モデルは記述的な詳細に反応し、曖昧なプロンプトはデバッグ不可能な予測不能な結果を生みます。
  • ヘッダーは交渉の余地がありません:bearer token は認証に使用され、Content-Type: application/json はサーバーにボディの解析方法を伝えます。

成功すると、生成画像への参照(通常は URL またはホストされたリソース)とメタデータを含む JSON レスポンスが返ります。レスポンスヘッダーも一緒に確認したい場合は、まず -sS で抑制せずに curl を実行して完全なレスポンスを出力し、構造を把握してから絞り込んでください。実際のレスポンスをファイルに保存しておきましょう。Python クライアントの作成とテスト時にテストフィクスチャとして使えます。

失敗した場合、反射的にリクエストボディを適当に変えないでください。まずステータスコードとエラーメッセージボディを確認してください。本ガイド後半のトラブルシューティング章で、各失敗カテゴリを具体的な修正方法に対応付けます。

リクエストを Python に移植する

curl が動作したら、セマンティクスを変えずに Python に移植します。目標はフレームワークを構築することではなく、シェルコマンドと完全に同じ動作をする、拡張しやすい小さなクライアントです。

最もクリーンな方法は、リクエストボディを共有の場所に置き、curl 版と Python 版が決してずれないようにすることです。それを辞書として定義し、シリアライズし、軽量なラッパーが HTTP 関連の処理を担当します。

import json
import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def build_payload(prompt: str, **overrides) -> dict:
    payload = {
        "model": "flux-3-image-klein",
        "prompt": prompt,
    }
    payload.update(overrides)
    return payload


def generate_image(prompt: str, timeout: float = 60.0, **overrides) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(build_payload(prompt, **overrides)),
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "夕暮れの崖の上に建つ風化した灯台、長露光、柔らかな霧"
    )
    print(json.dumps(result, indent=2))

この構造がなぜ理にかなっているか:

  • build_payload はリクエストボディを組み立てる唯一の場所です。そこにパラメータを追加すれば、探索スクリプトも本番コードも自動的にそれを得ます。
  • raise_for_status() は HTTP 失敗を即座に例外に変換するため、エラーレスポンスボディを誤って成功結果として扱うことは決してありません。
  • 明示的な timeout は古典的なハング問題を防ぎます:停滞した接続がワーカースレッドを無期限にブロックする状況です。サービス自身のリクエスト予算に合う値を選んでください。
  • base URL と key の両方に環境変数を使用することで、同じコードが修正なしにステージングと本番で実行できます。

実行して、出力を先ほど保存した curl レスポンスと比較してください。同じ構造を記述しているはずです。異なる場合、移植時にバグが混入しています。今のうちに修正してください。バッチ処理とリトライが加わると、差異ははるかに見苦しくなります。

サイズとスタイルのパラメータを扱う

プロンプトが大部分を解決しますが、画像に影響するパラメータ(出力サイズとスタイル関連のヒント)こそが統合が静かに壊れる場所です。2つのルールで安全を保てます。

任意パラメータを明示的なブロックにまとめる

マジック文字列をコード全体に散らばせないでください。名前付きパラメータでリクエストボディビルダーを拡張し、境界で検証します:

def build_payload(prompt: str, size: str | None = None, style: str | None = None) -> dict:
    payload = {"model": "flux-3-image-klein", "prompt": prompt}
    if size:
        payload["size"] = size
    if style:
        payload["style"] = style
    return payload

パラメータを完全に省略する方が、空文字列やプレースホルダーを送るより通常は優れています。サイズを制御する必要がなければ省略し、サービスにドキュメント通りのデフォルトを適用させてください。

仮定ではなくドキュメントに基づいて検証する

これはほとんどのチュートリアルが飛ばす部分です:ブログ記事から「サポートされる」サイズやスタイル値のリストをハードコードしないでください。 サポート値は変わりうるため、古い定数は追跡困難な実行時の 400 になります。代わりに:

  1. HiAPI ドキュメントで flux-3-image-klein の現在のパラメータリファレンスを読み、許容値をコードベース内の定数として記録し、ドキュメントページと確認日をコメントで注記します。
  2. リクエストを構築する前に、その定数でユーザーまたは呼び出し元の入力を検証します。失敗する運命のリクエストをネットワークに送るのではなく、明確なローカルエラーメッセージで早く失敗させます。
  3. サポートされない値でリクエストが検証エラーを返した場合、ドキュメントから定数を更新し、「正しそうに見える」近い値を推測しないでください。

小さな ALLOWED_SIZES タプルとメンバーシップチェック1行はほぼゼロコストで、サポートチケットのカテゴリ全体を排除できます。スタイルヒントも同様です:サーバーが許容することを願う開いた文字列ではなく、検証済みの閉じた集合として扱ってください。

バッチリクエストと失敗時のリトライ

スクリプト内の1リクエストはデモに過ぎません。実際の負荷は数十から数千枚の画像を意味し、そこでクライアント層の規律が重要になります。バッチ処理とリトライロジックは、ノートブックの場当たり的なループに貼り付けるのではなく、クライアントモジュールに置いてください。観察と調整のための1つの場所が欲しいからです。

トレーサビリティを備えた並行処理

シンプルなパターンは境界付きスレッドプールで、各サブミットされたタスクが入力と結果の両方を返します:

from concurrent.futures import ThreadPoolExecutor, as_completed

def run_batch(prompts: list[str], max_workers: int = 4) -> list[dict]:
    results = []
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {pool.submit(generate_image, p): p for p in prompts}
        for future in as_completed(futures):
            prompt = futures[future]
            try:
                results.append({"prompt": prompt, "ok": True, "data": future.result()})
            except Exception as exc:
                results.append({"prompt": prompt, "ok": False, "error": str(exc)})
    return results

ここには2つの重要な特性があります。第一に、各結果はそのプロンプトに関連付けられるため、部分的な失敗が謎ではなく帰属可能になります。第二に、max_workers はあなたが制御できる調整つまみです。保守的な値から始め、エラー率を観察し、バッチ実行がクリーンになってから初めて並行度を上げてください。無制限の並列でエンドポイントを猛攻撃することは、健全な統合をレート制限事故に変える最速の方法です。

バックオフ付きリトライ

安全なものだけをリトライしてください:一時的なネットワークエラー、タイムアウト、レート制限レスポンスです。検証エラーはリトライしないでください。リクエストは毎回同じように失敗し、クォータを浪費するだけです。

import time

def generate_with_retry(prompt: str, attempts: int = 3, **overrides) -> dict:
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, **overrides)
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise
            if attempt == attempts:
                raise
        except requests.Timeout:
            if attempt == attempts:
                raise
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("unreachable")

各試行ごとに、プロンプト識別子、試行回数、ステータスを含むログを1行記録してください。バッチ実行で問題が起きたとき、一時的な揺らぎなのか体系的なリクエストボディの問題なのかを教えてくれるのはこのログです。

よくあるリクエストエラーのトラブルシューティング

最初の週の失敗のほとんどはモデルの問題ではなく、パイプラインの問題です。以下は最も遭遇しやすいカテゴリと、それぞれの具体的な修正方法です。

401 / 403 — 認証と認可

症状:生成が起こる前に即座に拒否される。 原因:Authorization ヘッダーの欠落、bearer token の形式誤り、キーの期限切れまたは失効、あるいは環境変数に貼り付けた空白文字。 修正:実際に送信しているキーの先頭と末尾の数文字を出力し(完全なキーは決して出力しない)、ヘッダー形式が Bearer <key> でスペースがちょうど1つであることを確認し、キーが HiAPI アカウントで有効であることを確認します。curl では動くが Python では動かない場合、差異はほぼ常にヘッダーの組み立て方にあります。

400 — リクエストボディの検証

症状:リクエストは理解されるが、あるフィールドで拒否される。 原因:model のタイポ、prompt の欠落、サポートされない size やスタイル値、または型エラー(文字列が必要な場所に数値を渡した)。 修正:シリアライズしたリクエストボディ(json.dumps(build_payload(...)))をドキュメントのスキーマと文字単位で比較してください。任意パラメータをドキュメント由来の定数でローカル検証し、不正な値がプロセスから出ないようにします。

404 — ルートエラー

症状:エンドポイント自体が見つからない。 原因:パスのタイポ、古い base URL、または URL フラグメントを結合する際のスラッシュの不整合。 修正:コピーしたスニペットではなく、単一の定数から URL を構築し、HiAPI ドキュメントのエンドポイントリファレンスと照合してください。

429 — レート制限

症状:リクエストは成功し始めるが、負荷の下でまとめて失敗する。 修正:max_workers を下げ、リトライラッパーに既にあるバックオフ戦略を遵守し、429 を一時的エラーとして扱います。低並行度でも 429 が続く場合、コードではなくアカウントの制限や使用パターンを確認する必要があります。

タイムアウトと接続リセット

症状:呼び出しが長時間ハングする、またはバッチ途中で ReadTimeout 例外が発生する。 原因:クライアントのタイムアウトが攻撃的すぎる、ネットワーク不安定、または大きなバッチが接続プールを飽和させている。 修正:リクエストごとに明示的だが現実的なタイムアウトを設定し、タイムアウトにはバックオフ付きリトライを適用し、並行度を適度に保ちます。「動くようにする」ためにタイムアウトを削除しないでください。それは可視の失敗を不可視のハングに変えるだけです。

成功したが画像が違う

これは API の問題ではなくプロンプトの問題です。曖昧なプロンプト、矛盾するスタイルヒント、明示的な size と抵触するプロンプトは予期しない出力を生みます。まずプロンプトの記述を洗練させ、その後でパラメータを見直してください。

本番投入前のチェックリスト

本番トラフィックを flux-3-image-klein に向ける前に、このチェックリストを一通り実行してください。数分で済みますが、本番で高くつく失敗を捕まえられます。

  • 認証情報 — キーは環境変数またはシークレットマネージャーから読み込まれ、決してコミットされていない。課金予定のアカウントで画像生成に使用できることを確認済み。
  • エンドポイント — base URL とルートは現在の HiAPI ドキュメントから逐語的に取得され、単一の定数として保存されている。
  • リクエストボディ構造 — モデル名はドキュメントと完全に一致して綴られ、prompt は常に存在して非空、任意パラメータは未使用時は省略され、設定時はローカル検証される。
  • パラメータ値 — size とスタイルの定数はコメントに記載した日付時点のドキュメントと照合済みで、API 更新後に再確認する計画がある。
  • リトライ戦略 — 一時的エラーとタイムアウトはバックオフ付きでリトライし、クライアントエラーは早く失敗し、試行回数には上限がある。
  • 並行度 — max_workers は保守的に設定され、クリーンなバッチ実行後にのみ引き上げられる。
  • タイムアウト — すべてのリクエストに明示的に設定され、停滞した呼び出しがワーカースレッドを永久にブロックする経路が存在しない。
  • 可観測性 — 試行ごとに1行のログがあり、プロンプト識別子、試行回数、ステータス、レイテンシを含む。バッチ出力の各リクエスト結果は帰属可能。
  • 失敗アーティファクト — 少なくとも1つの実際の成功レスポンスと1つの実際のエラーレスポンスをテストフィクスチャとして保存済み。

未チェックの項目があれば、深夜2時にデバッグするより今修正する方が安く済みます。チェックリストがすべて緑になれば、触るのが怖いスクリプトではなく、小さく、可観測で、拡張可能なクライアントが手に入ります。権威あるパラメータリファレンスとエンドポイント更新については、HiAPI ドキュメントをブックマークし、最終的な根拠としてください。

永続的なAIアーティファクトで開発を始める

APIキーを取得して、タスクベースの1つのAPIで画像・動画・音声モデルを呼び出せます。

APIドキュメントを読む