HiAPI API で flux-1.1-pro を使う方法：curl、Python、そして実行可能なリクエスト

コードを書き始める前に：flux-1.1-pro が提供するもの

flux-1.1-pro はテキストから画像を生成するモデルで、HiAPI.ai がホストするエンドポイントとして呼び出します。プロンプトと生成パラメータを JSON で送信すると、生成された画像が返ってきます。何かをインストールする必要も、重みを自分でホストする必要も、GPU リソースを管理する必要もありません。統合する対象は HTTP エンドポイント 1 つと、認証用の資格情報だけです。

開発者にとって、これは最初の 1 行を書く前に設計を形作る 3 つのことを意味します。

第一に、リクエストは JSON イン・画像アウトです。プロンプト、アスペクト比、少数の制御パラメータはすべてリクエストボディに入ります。レスポンスはタスクの配信方式に応じて、画像データそのもの、または画像データへの参照を返します。リクエストボディを契約とみなし、1 か所に集約しておけば、curl と Python の 2 つの経路が決してずれることはありません。

第二に、画像生成は通常の API 呼び出しに比べて遅い操作です。数秒かかるのは正常で、高解像度で複雑なプロンプトならさらに時間がかかる場合があります。本番環境の呼び出し側は、呼び出しをデータベース読み取りのように扱うのではなく、遅延が存在する前提で計画しなければなりません。

第三に、出力品質は主にプロンプトで決まるものであり、配線で決まるものではありません。統合は簡単な部分です。本当の腕の見せどころは、欲しいものを正確に記述し、本番前に実際の出力でレシピを検証することです。

この 3 点を押さえれば、本ガイドの残りは機械的な流れです。リクエストを組み立て、動作を確認し、移植し、そして堅牢化とチューニングを行います。一貫して、すべては HiAPI API を通してルーティングされます。資格情報は 1 つ、ベース URL は 1 つ、学ぶべき JSON 構造は 1 つだけです。

最初の curl リクエスト

curl から始めましょう。これにより、あなたとエンドポイントの間の抽象化レイヤーがすべて取り除かれるため、失敗したときに問題がフレームワークではなくリクエストボディにあることが明確になります。

最小限の呼び出しは 3 つの部分から成ります。エンドポイント、認証ヘッダー、そして JSON リクエストボディです。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "prompt": "a ceramic coffee mug on a weathered wooden table, soft morning window light, shallow depth of field, product photography",
    "aspect_ratio": "1:1"
  }'

リクエストボディをフィールドごとに読み解きます。

• model は使用するモデルを指定します。将来デフォルト値が変更されても出力が黙って変わらないよう、明示的に記述してください。
• prompt は自然言語の記述です。品質に関する予算のほぼすべてがここに集約されます。
• aspect_ratio は構図を制御します。検証していないデフォルトに頼らず、意図をもって選択してください。

キーはコマンドに直接貼り付けるのではなく、環境変数（HIAPI_API_KEY）に入れてください。この習慣はそのまま Python に、そして後で追加するあらゆる CI ステップに引き継がれます。

呼び出しが成功すると、完成した画像を記述した JSON レスポンスが返ってきます。ターミナルを閉じる前に、それを確認し、画像への参照またはデータを特定してください。呼び出しが失敗すると、ステータスコードとメッセージを含むエラーボディが返ってきます。メッセージを文字通りに読んでください。フィールドの形式エラーが最初の失敗で最もよくある原因だからです。

1 時間を節約できる警告を 1 つ。エスケープされていない引用符を含む複数行のプロンプトをシェルに貼り付けないでください。短いフレーズより長い内容には、ヒアドキュメントかファイルを使ってください。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

この request.json こそがバージョン管理にコミットすべき成果物です。これはリクエストボディの唯一の信頼できる情報源であり、次のセクションでそのまま再利用します。

同じ呼び出しを Python に移植する

移植の目的は新しいロジックを書くことではなく、まったく同じ JSON リクエストボディを送信することです。同じ request.json を読み込むことで、2 つの経路がずれるのを防ぎます。

import json
import os

import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"

with open("request.json") as f:
    payload = json.load(f)

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

if response.status_code != 200:
    print(response.status_code)
    print(response.text)
    response.raise_for_status()

print(response.json())

ここでは 3 つの細部が重要です。

認証ヘッダーは通常のヘッダーと同じセットです。 json=payload を使うと requests がボディをシリアライズし、Content-Type を設定します。ヘッダーを明示的に書いても害はなく、意図を記録できます。

タイムアウトを設定してください。 生成リクエストを無制限のデフォルト値に放置してはいけません。余裕のある明示的なタイムアウトで構いません。重要なのはそれが明示的であることです。

例外を投げる前にエラーボディを確認してください。 先に raise_for_status() を実行すると、レスポンスボディがログから失われます。まずステータスコードとテキストを出力してから例外を投げてください。あるフィールドが拒否されたとき、そのテキストが必要になります。

非同期 HTTP クライアントに統一している場合も構造は変わりません。同じ URL、同じヘッダー、同じボディで、ただ await client.post(...) を使い、同じタイムアウトを設定します。リクエストボディの契約は定数であり、クライアントは実装の詳細です。

リクエストボディは Python のソースコードの外に置いてください。プロンプトのレシピが有効になったら、それは関数内の文字列リテラルに埋め込むのではなく、ファイルかデータベースの行に属すべきです。そうすれば diff を取り、再実行できます。

アプリをブロックせずに非同期タスクを処理する

生成は関数呼び出しではなくタスクとして扱ってください。配信経路が同期的に見える場合でも、ポーリングが必要なタスクを返す場合でも、実際の結果は同じです。アプリは 1 枚の画像を待つためにリクエストスレッドを無制限に占有してはいけません。

実用的なパターンは 4 つのステップで構成されます。

1. ユーザーリクエストからではなく、ワーカーから送信する

Web 層でユーザーの生成操作を受け付け、タスクレコードを永続化し、キューに入れて、すぐに返します。実際の API 呼び出しはバックグラウンドワーカーが実行します。ユーザーがポーリングするのはあなたのエンドポイントであり、モデルではありません。

2. 待機に上限を設ける

各試行に、意図的に選んだタイムアウトを設定します。プラットフォームがポーリングすべきタスクを返す場合は、固定間隔、最大試行回数、そして試行回数ではなくタスク開始時刻から計算した期限でポーリングします。タイトなループより、適度なバックオフを優先してください。

3. 再試行する価値のある失敗だけを再試行する

転送エラー、タイムアウト、サーバー側の失敗には、指数バックオフとジッターを使い、少ない試行回数に制限して再試行します。検証エラーは再試行しないでください。拒否されたフィールドや空のプロンプトは毎回同じように失敗するため、再試行してもユーザーが本当のメッセージを見る前に待たされるだけです。

4. あなた側でタスクを冪等にする

データベースに正確なリクエストボディとタスク ID を記録します。ワーカーが送信後、成功を記録する前にクラッシュした場合、盲目的に再送信するのではなく、そのタスクを再確認できます。再送信が必要な場合は、短いクライアント側の重複排除キーを追加して、一時的な障害が同じ生成を 3 回キューに入れないようにします。

import time

def poll_until_done(fetch_status, job_id, deadline_seconds=180):
    start = time.monotonic()
    delay = 2.0
    while True:
        status = fetch_status(job_id)
        if status["state"] in ("succeeded", "failed"):
            return status
        if time.monotonic() - start > deadline_seconds:
            raise TimeoutError(f"generation {job_id} exceeded deadline")
        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)

このヘルパーは意図的に汎用的に保っています。ステータスを取得する関数を受け取るので、同じループが後で統合するあらゆるタスク型エンドポイントに使えます。重要な特性は期限、上限付きのバックオフ、終端状態のチェックであり、具体的な転送方式ではありません。

安定してレンダリングされるプロンプトを組み立てる

長いプロンプトが良いプロンプトとは限りません。構造が重要です。再現可能な骨格があれば一貫した結果が得られ、問題が起きたときには 1 度に 1 つの変数だけを変える場所ができます。

次の順序で 4 つのスロットを使ってください。

1. 主体——画面に何があるか。具体的に。「カフェで使う何か」より「セラミックのコーヒーマグ」のほうが優れています。
2. スタイル——視覚的な基調。写真、イラスト、水彩、3D レンダリング、商品撮影など。媒体を明記し、必要なら光についても書きます。
3. 構図——フレーミングとカメラ。アスペクト比、撮影距離、アングル、被写界深度、画面内の主体の位置。
4. 制約——明確に欲しいものと欲しくないもの。簡潔に。

[subject] a single ceramic coffee mug, matte glaze, small handle
[style] product photography, soft diffused window light, muted palette
[composition] 1:1, eye-level, subject centered, shallow depth of field, plain background
[constraints] no text, no logos, no hands

送信時にはこれを 1 つのプロンプトに平坦化します。角括弧はあなた自身のためのものであり、モデルのためのものではありません。スロットで書く価値は、出力がおかしいときにどのスロットを編集すべきか分かることです。

実用的なルールをいくつか。

• 主体を先頭に置く。 最初の節が最も重みを持ちます。
• 抽象的な感情語より、具体的な名詞と形容詞を優先する。 「マットな釉薬」はピクセルを変えますが、「高級感」はほとんど変えません。
• カメラ用語は主体スロットではなく構図スロットに入れる。 混ぜるとせっかちで矛盾した指示になります。
• 反復時は一度に 1 つのスロットだけを変え、採用された出力を生んだ正確なプロンプトテキストを保存してください。

アスペクト比は事後のパッチではなく構図の決定です。画像が表示される場所に合わせて選んでください。グリッドなら正方形、ヒーローバナーならより縦長に。そしてプロンプトの残りをそのフレームに合わせます。

ネガティブワードリストを効果的に使う

ネガティブワードリストはモデルに避けるべきものを伝えます。鋭いツールですが有用な範囲は狭く、繰り返し現れる瑕疵の抑制には最適ですが、思いつく限りの不完全さを並べるゴミ箱としては最悪です。

ネガティブワードは短く具体的にしてください。ほとんどのプロンプトでは、5 から 8 個の短い項目で十分です。具体的なものを書きます。

no text, no watermark, no logos, no extra fingers, no harsh shadows

このリストが機能するのは、各項目が目に見えて確認可能なものを名指しているからです。「not ugly」や「bad quality」のような曖昧な否定と比べてみてください。それらは実行可能な信号をほとんど運ばず、本当に重要な項目を薄めてしまいます。

ネガティブワードが本当に役立つ場面。

• 繰り返し見える瑕疵の抑制。 手や文字が繰り返し現れるなら、それらを直接書くのが最も直接的な修正です。
• ブランドと法的な衛生。 画像がユーザー向け画面に届く前にロゴや透かしを排除します。
• 商品画像や UI に近い画像でクリーンな背景を強制する。

裏目に出る場面。

• ポジティブプロンプトとの矛盾。 ネガティブの「影なし」と主体の「ドラマチックなサイドライト」の対立は、モデルが予測不能な方法で解決する衝突です。ポジティブプロンプトを直すべきです。
• そもそも現れそうにないものを否定する。 ありそうにない失敗項目の長いリストはノイズを増やすだけで、レンダリング結果を変えません。
• 曖昧な主体をネガティブワードで補う。 主体が不明確なら、どんなネガティブワードリストも救えません。

実用的な細部を 1 つ。一部のクライアントはネガティブワードを追加テキストではなく別フィールドとして受け付けます。あなたのリクエストがどちらをサポートするか確認し、そのフィールドを保存したリクエストボディに残して、curl と Python の挙動が完全に一致するようにしてください。

実際の出力を伴うプロンプトレシピ

以下のレシピは出発点であり、保証ではありません。正直なワークフローとは、自分の統合を通してレシピを実行し、出力を見て、1 つのスロットを調整することです。自分で生成していない出力は、すべて未検証とみなしてください。

レシピ 1——クリーンな商品画像

A single matte-black wireless earbud case on a light concrete surface,
studio product photography, soft key light from the left, 1:1, centered,
shallow depth of field, plain background. No text, no logos, no hands.

期待される特徴：くっきりとした中央の主体、柔らかな減衰、雑然としない背景。表面がごちゃごちゃしすぎるなら「plain background」を引き締め、テクスチャの語を削除します。光が平坦すぎるなら方向性のあるキーワードを加えます。それだけです。

レシピ 2——エディトリアルポートレート

Portrait of a person in a wool coat, natural window light, calm expression,
3:4, chest-up framing, subject slightly off-center, muted film palette.
No text, no watermark.

期待される特徴：柔らかな指向性の光、抑制された色味。フレーミングが想定より広いなら「chest-up framing」を先頭に移し、競合する構図の語を削除します。

レシピ 3——アイソメトリックイラスト

Isometric illustration of a small reading nook: armchair, floor lamp, bookshelf,
flat vector style, limited palette of warm neutrals and one accent color,
1:1, centered composition, clean white background. No text, no gradients.

期待される特徴：明快な幾何構造とフラットな塗り。配色が外れるならアクセントカラーを明記し、「clean white background」を最後の節に残して勝たせます。

レシピ 4——ヒーローバナー

A wide misty mountain ridge at sunrise, layered depth, minimal detail,
16:9, subject occupying the lower third, generous empty sky for overlaid text.
No text, no watermark.

期待される特徴：静かでディテールの少ない画像と、使えるネガティブスペース。「overlaid text」という表現はスペースを確保するもので、文字をレンダリングしません。ネガティブワードリストが画像自体に文字を入れさせないようにします。

各レシピについて、正確なリクエストボディ、アスペクト比、日付を記録してください。1 か月後に振り返るとき、記録したリクエストボディを再実行し、記録した出力と比較できます。結果がなぜ変わったかを推測する必要はありません。

エラー、制限、そしてまず何を確認するか

生成が失敗した、あるいは出力がおかしいとき、コードを変える前にこのチェックリストを順に確認してください。

まずリクエストボディを確認する

• ボディは有効な JSON ですか？ 末尾のカンマやエスケープされていない引用符が最初の失敗で最もよくある原因です。送信前に保存した request.json を検証してください。
• フィールド名は完全に正しいですか？ 綴りを間違えたパラメータは通常拒否されるか、黙って無視されます。記憶ではなくドキュメントのリクエスト構造と照合してください。
• モデル名は正しく存在しますか？ デフォルトに頼らないでください。
• プロンプトは空でなく、ドキュメントの長さ制限内ですか？ 制限はプラットフォームのドキュメントに書かれています。数字を仮定せず、そこで読んでください。

次に認証と転送を確認する

• API キーは存在し、現在有効ですか？ 401 は通常、ヘッダーの欠落、形式の誤り、またはキーがローテーションされたことを意味します。
• エンドポイント URL とメソッドは正しいですか？ GET パスに POST を送ると、キーの問題のように見える失敗になります。
• タイムアウトが厳しすぎませんか？ タスクが完了する前にクライアントが諦めると、目にするタイムアウトはモデルとは無関係です。

次にリクエスト構造を確認する

• ステータスコードの区分がどこを見るべきかを教えてくれます。 4xx はほぼ常にリクエスト側の問題、5xx は通常一時的で、上限付きの再試行に値します。
• エラーメッセージを文字通りに読む。 例外を投げる前にレスポンスボディを出力してください。メッセージに挙がっているフィールドが修正すべきフィールドです。
• レート制限やクォータのレスポンスは、プロンプトを書き換えるのではなく、速度を落としてバックオフ付きで再試行することを意味します。

最後にプロンプトを確認する

呼び出しは成功したが画像がおかしい場合、あなたはエラーの領域ではなくプロンプトの領域にいます。

• 主体が欠けている、または一般化しすぎている？ 最初の節に移し、具体的にしてください。
• 構図が違う？ アスペクト比とフレーミングの語を同時に直してください。片方でもう片方を補おうとしないでください。
• 瑕疵が繰り返し現れる？ 短く具体的なネガティブワードを 1 つ加えます。
• 矛盾がある？ ポジティブプロンプトと対立するネガティブワードを見つけて削除します。

最も重要なのは 1 つの習慣を保つことです。気にかけるすべての生成について、正確なリクエストボディ、レスポンスステータス、生成された画像への参照を記録してください。再現性があれば、デバッグは推測から diff に変わります。最初のリクエストを組み立て、出力を確認し、本番前にプロンプトを引き締めてください。そして本番で使ったリクエストボディを保存しておけば、次の変更には比較できる真の基準ができます。