HiAPI
ブログ

チュートリアル

HiAPI API で flux-2/text-to-image を呼び出す方法:curl と Python チュートリアル

動作するリクエストの演習:モデル識別子、プロンプトとアスペクト比のパラメータ、レスポンスフィールド、エラー処理

Nov 12, 2026
カバー画像:濃いインディゴの背景に、幅広の矢印が入れ子状に重なり合って順に右へ進み、先端はアプリコットオレンジで、信号フロー図のようにフラットで精密。
このページの内容

flux-2/text-to-image が API 経由で公開しているもの

最初のコードを書く前に、自分が何に接続しようとしているのかを明確にしておくと役立ちます。HiAPI において、flux-2/text-to-image はインストールすべき個別の SDK でも、個別の認証が必要な新しいサービスでもありません。これはモデル識別子であり、描きたい画面を記述したプロンプトと一緒に、共有の画像生成エンドポイントへ渡します。

このメンタルモデルは重要です。なぜなら、統合の境界を明確にしてくれるからです。あなたのコードに必要なものは 3 つだけです:

  • HiAPI API 用の認証情報。
  • 画像生成リクエストを受け付けるエンドポイント。
  • model(flux-2/text-to-image に設定)と prompt を含む JSON ペイロード。

それ以外のすべて——アスペクト比、出力の好み、モデルが公開しているその他の調整項目——は、このペイロード内の追加フィールドとして存在します。だからこそ、別のテキスト・トゥ・イメージモデルから flux-2/text-to-image への切り替えは、コードの書き直しではなく、通常は 1 行の設定変更で済みます。リクエストのエンベロープは変わらず、変わるのは model の値だけです。

エンドポイントはリクエストを受け取り、モデルを通して実行し、生成された画像(通常は URL またはエンコードされたペイロード)とジョブのメタデータを含む構造化されたレスポンスを返します。基本的な呼び出しでは、別のジョブキューをポーリングする必要はありません——クライアントから見ると、リクエスト/レスポンスのサイクルは同期的ですが、実際の生成には時間がかかるため、HTTP クライアントのタイムアウトは余裕を持って設定すべきです。

この全体像を覚えておいてください:1 つのエンドポイント、1 つのペイロード、1 つのモデル文字列。このチュートリアルの残りの部分では、ペイロードを埋めて呼び出しを堅牢にしていきます。

curl で動作するリクエストを構築する

認証情報とペイロード構造が正しいことを確認する最速の方法は、curl を 1 回呼び出すことです。Python に触る前に、ターミナルで一度成功レスポンスを得ておきましょう——これにより、認証やペイロードの問題を、言語レベルのバグから切り離すことができます。

まず、キーを環境変数に設定して、シェル履歴に平文で残らないようにします:

export HIAPI_API_KEY="your_api_key_here"

次にリクエストを送信します:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "prompt": "夜明けの花崗岩の崖の上に立つ風化した灯台、柔らかな霧、ワイドショット",
    "aspect_ratio": "16:9"
  }'

実行時に確認すべきポイント:

  • エンドポイントとキーは HiAPI アカウントのダッシュボードから取得します。ダッシュボードからエンドポイントをコピーし、再入力しないことで、最もよくあるサイレント障害——リクエストが意図しない場所に送られる——を回避できます。
  • -sS は出力を簡潔に保ちつつ、DNS や TLS の失敗など curl レベルのエラーは表示します。
  • Authorization ヘッダーは標準的な bearer スキームを使用します。変数展開の前後に末尾のスペースや引用符がないことを確認してください。
  • Content-Type: application/json は必須です。これがないと、リクエストボディがモデルに届く前に拒否される可能性があります。

呼び出しが成功すると、ターミナルに JSON レスポンスボディが表示されます。フォーマッタにパイプして可読性を高めましょう:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-2/text-to-image","prompt":"新雪の中の赤いキツネ、アイレベル","aspect_ratio":"1:1"}' \
  | python3 -m json.tool

これが動作すれば、既知の良好なベースラインが得られます。その後 Python での失敗は、すべてこの動作確認済みの呼び出しと比較できます。

プロンプトとアスペクト比のパラメータ

出力に最も大きく影響するリクエストフィールドは 2 つあります:prompt と aspect_ratio です。一度に 1 つだけ調整してください。そうしないと、目の前の変化がどちらによって引き起こされたのか判断できなくなります。

プロンプト

プロンプトは画像の自然言語による記述です。キーワードの羅列ではなく、簡潔なシーン描写として書いてください——おおよそ、被写体、場面、光、構図の順に。比較してみましょう:

  • 曖昧:灯台
  • 具体的:夜明けの花崗岩の崖の上に立つ風化した灯台、柔らかな霧、ワイドショット

実験中は表現を明確かつ安定に保ってください。同じイテレーションでプロンプトとアスペクト比の両方を書き換えると、変数が 2 つ、観察が 1 回になってしまいます。プロンプトを固定し、一度に 1 語ずつ調整し、実際の変化を記録しましょう。

実用的な習慣:

  • 最も重要な被写体を文字列の前半に置く。
  • 光や雰囲気は抽象的ではなく具体的な言葉で記述する。
  • コードベースに少数の参照プロンプトを保持し、他の何かを変更するたびにそれらを再実行して、モデルの挙動変化とプロンプトの変化を区別できるようにする。

アスペクト比

aspect_ratio は出力の形を制御します——風景やバナーにはワイド、アバターやサムネイルにはスクエア、ポスターやモバイルレイアウトには縦長です。モデルは 16:9、1:1、または縦長の同等物などの比率文字列を受け付けます。勝手に発明するのではなく、モデルのドキュメントに記載されている比率を使用してください。

アスペクト比は単一の離散的なフィールドなので、最も簡単にスキャンできるパラメータです。プロンプトを固定したループを書き、同じ画像を 3 つの比率でリクエストし、構図を並べて比較しましょう。どの比率が被写体を切り取るのか、どの比率が被写体に余白を与えるのかがすぐに分かります。

1 つの注意点:アスペクト比はキャンバスだけでなく、実効的な構図を変えます。ワイドショット用に書かれたプロンプトは、スクエアのフレームでは薄っぺらく見えるかもしれません。比率を決めたら、補正のためにプロンプトをもう一度見直しましょう。

呼び出しを Python に移植する

curl 呼び出しは Python に直接変換できます。目標は、プロンプトとアスペクト比を受け取り、環境からキーを読み取り、パースされた JSON を返す小さな関数を書くことです——使い捨てスクリプトではなく、本番向けの形です。

import os
import requests

IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"


def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "aspect_ratio": aspect_ratio,
    }
    response = requests.post(
        IMAGE_ENDPOINT,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()

このように書く理由について:

  • リテラルではなく環境変数を使用する。os.environ[...] は変数が欠けていると即座に KeyError を投げます。これは、空の bearer トークンを送って後から分かりにくい認証エラーをデコードするよりはるかに優れています。
  • json=payload により、requests がボディをシリアライズし、Content-Type を設定してくれます。JSON 文字列を手動で構築しないでください。
  • 明示的なタイムアウト。画像生成は即時ではありません。デフォルトのクライアントタイムアウトは高負荷時に問題を引き起こします。意図的に設定してください。
  • raise_for_status() は非 2xx レスポンスを、データのように見えるエラーボディを静かに返すのではなく、キャッチして分類できる例外に変換します。

呼び出し方:

result = generate_image(
    "夜明けの花崗岩の崖の上に立つ風化した灯台、柔らかな霧、ワイドショット",
    aspect_ratio="16:9",
)
print(result)

httpx を好む場合も形はまったく同じです——インポートを変更し、同じヘッダー、json= ペイロード、タイムアウトパラメータを維持します。重要なのはペイロードであり、curl バージョンと変わりません。

レスポンスを読み取る

成功した呼び出しは JSON オブジェクトを返します。フィールド名を推測するのではなく、まず実際のレスポンスを検査し、実際に見た内容に基づいてパーサーを書きましょう。関数を実行してトップレベルのキーを出力します:

result = generate_image("新雪の中の赤いキツネ、アイレベル", "1:1")
print(result.keys())

通常使用するフィールドは 2 つのグループに分かれます:

  • 画像そのもの。レスポンスは生成された画像を運びます——通常はダウンロードまたは配信できる URL、時にはエンコードされた画像データです。自分のレスポンスから正確なフィールド名を読み取り、その値を保存し、その形式に応じて処理してください。URL の場合は短命なものとして扱いましょう:リンクをデータベースに保存して来月も解決できると仮定するのではなく、速やかにダウンロードするか自分のストレージにコピーしてください。
  • メタデータ。生成プロセスを記述する付随フィールドが期待されます——使用されたモデル、リクエストされたアスペクト比やサイズ、リクエストの識別子。画像と一緒に記録してください。ユーザーが画像が「おかしい」と報告したとき、メタデータがあれば、アプリケーションの状態から再導出することなく、どのプロンプトと比率がそれを生成したかを教えてくれます。

安全な抽出パターン:

image_ref = result.get("image") or result.get("data")
if not image_ref:
    raise ValueError(f"no image in response; keys={list(result.keys())}")

これは意図的に防御的に書かれています。フィールド名はモデル内で安定していますが、アクセサを実際のキーリストで大きく失敗する形で書くことで、サイレントな None が UI に伝播するのを防ぎます。実際のレスポンスでフィールド名を確認したら、コードを引き締めて直接読み取るようにしましょう。

最後に、生のレスポンスを捨てないでください。統合が安定するまでは保存しておきましょう(または部分的なリクエストのためにログに記録しましょう)——下流で異常が発生したとき、それが事実の根拠になります。

よくあるエラーとその修正方法

初回実行時の失敗のほとんどは、少数のカテゴリに分類されます。通知なく変化するメッセージテキストの文字列マッチングではなく、HTTP ステータスのカテゴリで処理してください。

認証失敗(401 / 403)

キーが欠けている、形式が誤っている、またはアクセス権限が不足しています。順番に確認してください:プロセスが見ている環境に HIAPI_API_KEY が実際に設定されているか;ヘッダーが正確に Authorization: Bearer <key> で、余分な空白や引用符で囲まれていないか;誤って別の環境のキーを送っていないか。curl は動くが Python は動かない場合、送信しているヘッダーを出力して 1 文字ずつ比較してください。

ペイロード形式エラー(400)

リクエストボディが生成前に拒否されています。よくある原因:無効な JSON(手動構築した文字列の末尾カンマ)、prompt の欠落、または Content-Type の誤り。修正方法は、Python では json=payload を使用し、curl では有効な JSON を指定した -d を使用することです。送信しようとしているペイロードをログに出力し、人間として読んでください。

サポートされていない、または無効なパラメータ(400 / 422)

モデルが受け付けないフィールド名や値——スペルミスの aspect_ratio、モデルに記載のない比率、または別のモデルの例からコピーした余分なフィールド。ペイロードを最小限(model、prompt)に減らし、その後フィールドを 1 つずつ追加して問題箇所を特定しましょう。

レート制限(429)

アカウントの制限が許す速度を超えてリクエストを送信しています。これは一時的なものです。タイトなループでリトライしないでください——遅延を増やし、試行回数に上限を設けたバックオフを使用してください。バッチ処理する場合は、一度にすべて送信するのではなく、呼び出しの間に小さな遅延を追加しましょう。

サーバー側エラー(5xx)とタイムアウト

これらは一時的で、あなたの制御の外にあります。バックオフでリトライし、遅い生成が失敗と誤分類されないよう、タイムアウトが十分長いことを確認してください。モデルがまだ動作中に発生した読み取りタイムアウトは、リトライを発生させ、1 つのリクエストを無駄にします。

分類を 1 か所にまとめることで保守性を保てます:

def classify(status: int) -> str:
    if status in (401, 403):
        return "auth"        # fix config, do not retry
    if status in (400, 422):
        return "payload"     # fix request, do not retry
    if status == 429:
        return "rate_limit"  # retry with backoff
    if status >= 500:
        return "server"      # retry with backoff
    return "other"

本番環境向けに呼び出しをラップする

上記の関数は動作しますが、実際の統合にはまだ備わっていない 3 つのものが必要です:一時的失敗と永続的失敗を区別するリトライ、現実を反映したタイムアウト、そして何が起こったかを再構築できるログ。小さなラッパーがこの 3 つをカバーします。

import logging
import time

log = logging.getLogger(__name__)

def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, aspect_ratio)
        except requests.HTTPError as exc:
            status = exc.response.status_code
            kind = classify(status)
            log.warning("flux-2 call failed", extra={
                "attempt": attempt, "status": status,
                "kind": kind, "aspect_ratio": aspect_ratio,
            })
            if kind in ("auth", "payload"):
                raise  # retrying will not help
            if attempt == attempts:
                raise
            time.sleep(delay)
            delay *= 2

各部分に価値がある理由:

  • リトライ可能なものだけをリトライする。認証とペイロードのエラーは決定的です——リトライしても時間を無駄にし、本当のバグを隠すだけです。レート制限、サーバーエラー、タイムアウトは指数バックオフの対象です。
  • 散文ではなく構造化フィールドを記録する。試行回数、ステータス、エラーカテゴリ、使用したパラメータにより、後から失敗をグループ化できます。API キーは決して記録しないでください。
  • 試行回数を制限する。無制限のリトライループは、1 回の障害をハングしたワーカープロセスに変えてしまいます。
  • タイムアウトを明示的かつ余裕を持たせる。設定から渡すことで、既知の低速時間帯にコードを変更せずに引き上げられます。

さらに報われる 2 つの習慣:生成された各画像について (model, prompt, aspect_ratio) のハッシュを永続化して、あらゆる出力を再現できるようにする;テストスイートに少数の参照プロンプトを保持し、ラッパーに変更を加えた後にそれらを実行する。両者を組み合わせることで、チュートリアルの断片が運用可能なものに変わります。

リクエストの形が確定し、エラー処理が整えば、その後モデルを変更するには model フィールドを 1 行変更するだけで済みます——これこそが、統一インターフェース経由で flux-2/text-to-image を呼び出すことの意義です。

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

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

APIドキュメントを読む