チュートリアル
HiAPI API で minimax-h3-image のテキスト-to-イメージを使う方法:curl と Python
このページの内容
このチュートリアルの範囲と、事前に用意するもの
このチュートリアルは一つの具体的なことだけを扱います。HiAPI API 経由で minimax-h3-image テキスト-to-イメージモデルに画像生成プロンプトを送信し、まず curl リクエストを一度行い、次にアプリに組み込める小さな Python 関数で実装します。リクエストの構造、レスポンスの読み解き方、エラーがどのように現れるか、そして本番環境に投入する前にどこを引き締めるべきかを扱います。
プロンプトエンジニアリングの理論、画像の後処理、UI の構築は意図的に扱いません。目標はもっと絞られています。読み終えたとき、信頼できるリクエストが手元にあり、前回失敗した正確な理由を把握しているべきです。
前提条件
- HiAPI アカウント。 何よりもまず、プロジェクトと API キーが必要です。以下のすべてのリクエストで認証が必要です。
- キーは安全な場所に保管する。 ソースファイルではなく環境変数(
HIAPI_API_KEY)に入れておけば、同じコードがローカルでも CI でも動作します。 - モデル識別子。 本チュートリアルでは
minimax-h3-imageとそのtext-to-image機能を使用します。モデル名とタスクパスの両方を、あちこちに散らばるマジック文字列ではなく、コード内の設定値として扱ってください。 - ツール。 最初のリクエストには
curl、2 つ目には Python 3.9+ とrequestsを使用します。他のライブラリは不要です。 - 画像を確認する手段。 画像データまたは画像への参照を含むレスポンスペイロードを読み取ります。スキーマを想定する前に、まずレスポンスのフィールドを手動で一度確認してください。
今すぐ身につけるべき習慣
アプリコードの外側で最初の成功するリクエストを先に生成してください。動作する curl コマンドは基準となる真実です。Python 版の挙動がおかしいときは常にそれと照合してください。curl 呼び出しが成功して Python が失敗するなら、問題はモデルやネットワークではなくクライアント側にあります。
curl で動作するテキスト-to-イメージリクエストを組み立てる
可能な限り最小のリクエストから始め、設定を一つずつ戻していきます。生成リクエストは 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": "minimax-h3-image",
"task": "text-to-image",
"prompt": "亜麻のテーブルクロスの上の陶器のボウル、柔らかな北窓の光、50mm レンズ、浅い被写界深度",
"size": "1024x1024",
"n": 1
}'
このコマンドには 3 つの注意点があります。
- キーはベアラートークンとして
Authorizationヘッダーで渡されます。URL やリクエストボディに入れてはいけません。ログやシェル履歴に残ってしまいます。 modelとtaskは何が欲しいか(モデル系列と機能)を記述します。デフォルト値が存在する場合でも、両方を明示的に書いてください。明示的なリクエストのほうが長持ちします。promptは普通の文字列です。それ以外(size、n)は画像設定であり、被写体の説明ではありません。
レスポンスを読み解く
出力をフォーマッタに通して、実際に読めるようにしましょう。
curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
反復作業中はリクエストボディをファイル(request.json)に入れてください。プロンプトが読みやすく保たれ、プロンプトの変更が引用符の当て推量ゲームではなく 1 行の diff になります。
パーサーを書く前にペイロードを確認してください。画像がインラインで返るのか URL で返るのか、どのフィールドが画像識別子と変更後のプロンプトを運ぶのか、レスポンスに使用量メタデータが含まれるのかに注意してください。これらのフィールド名をメモしてください。Python クライアントはこれらに依存します。
全体フローをエンドツーエンドで確認する
返された画像を保存し、開き、要求したものを受け取ったかを確認してください。妥当に見える JSON ボディを伴う 200 レスポンスは、正しい画像を意味しません。まさにこの時点で、プロンプトとパラメータの問題が最も安く発見されます。
リクエストを Python に翻訳する
まったく同じリクエストを移植します。平凡さを保ってください。1 つの関数、明示的なタイムアウト、当面は隠れたリトライなしです。
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""HiAPI 経由で minimax-h3-image を使って画像を生成する。"""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # 接続タイムアウト、読み取りタイムアウト
)
response.raise_for_status()
return response.json()
この関数には 4 つの意図的な選択があります。
- タプルタイムアウト。 接続確立が遅いのは問題の兆候なので接続タイムアウトは短くし、画像生成には本来時間がかかるので読み取りタイムアウトは寛容にします。単一のタイムアウト値では、1 つの失敗モードでしかうまく扱えません。
json=payload。 ボディのシリアライズはライブラリに任せます。手で組み立てた JSON 文字列は引用符バグの温床です。- パース前の
raise_for_status()。 ステータスチェックはオプションではありません。エラーレスポンスボディを成功としてパースすることは、この種の統合で最も混乱を招くバグです。 - 素の
dictを返す。 後で型付きモデルで飾ることはできます。まずレスポンスが実際にどのフィールドを含むのかを把握してください。
キーの検索を分離する
変数が存在しない場合、os.environ["HIAPI_API_KEY"] は即座に例外を投げます。これは意図的です。最初のユーザーリクエスト時ではなく、起動時に失敗させます。より大きなコードベースでは、設定読み込み時にキーを一度解決し、呼び出し箇所で環境変数を読むのではなく、設定済みクライアントを渡してください。
実行に接続する
if __name__ == "__main__":
result = generate_image("引き潮の濡れた浜辺の上を飛ぶ赤い凧、曇天の光")
print(result)
実行して curl の出力と比較してください。ペイロード構造は一致するはずです。一致しなければ、構築を続ける前に解明すべき差異を見つけたことになります。
推測ではなくエラーを処理する
最もよくある統合バグは、決して成功しないエラーをリトライすることです。失敗を 3 つのカテゴリに分け、区別して扱ってください。
認証と認可の失敗
これらは通常 401 または 403 として現れます。原因には、ヘッダーの欠落、Bearer プレフィックスの形式エラー、キーの失効や設定ミス、プロジェクトにそのモデルへのアクセス権がないことなどがあります。これらはリトライ不可です。リトライは時間を浪費するだけで、同じ失敗でログを汚します。資格情報を修正して先に進んでください。
リクエスト検証の失敗
これらは通常 400 レベルのレスポンスです。未知の model や task の値、モデルがサポートしない size、範囲外の n、空のプロンプト、不正な形式の JSON などです。同様にリトライ不可です。同じリクエストは同じように失敗します。有益なのは、そのリクエストを書いた開発者にエラーメッセージをそのまま提示することであり、汎用例外に飲み込むことではありません。
一時的なサーバーとネットワークの失敗
429 と 5xx レスポンス、および接続リセットや読み取りタイムアウトが、本当にリトライ可能なカテゴリです。上限付きの指数バックオフとジッターで処理します。
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"一時的エラー {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
2 つの注意点があります。第一に、429 以外の 4xx によって発生した HTTPError は即座に外へ投げなければなりません。except 節に検証失敗を吸収させてはいけません。第二に、独自の遅延を発明するのではなく、レスポンスに含まれるリトライ指示に従ってください。
ここでのリトライは冪等ではない
リトライされた生成のそれぞれは新たな課金対象の生成です。リクエストがタイムアウトしても、画像はすでに生成され課金されている可能性があります。リトライ回数は小さく保ち、試行回数をリクエストメタデータと一緒にログに記録し、同じ画像を 4 回静かに生成するより、明確な失敗を提示することを優先してください。
プロンプトとパラメータの実用的な衛生習慣
これらの習慣の意義は比較可能性にあります。1 つのことを変えたとき、出力の変化がそれによって引き起こされたかを判断できるべきです。
画面の内容を明示するプロンプトを書く
被写体、シーン、光、構図の順に記述してください。具体的な名詞や写真用語(「柔らかな北窓の光」「浅い被写界深度」など)は、美学形容詞を積み重ねるより多くのシグナルを持ちます。否定的なプロンプトを多用せず、現れるべき内容を記述してください。
一度に 1 つの変数だけを変える
各プロジェクトに小さなプロンプトファイルを 1 つ置き、ゼロから書き直すのではなく実行間でそれを編集してください。ある実行が期待外れなら、プロンプトか設定のどちらか一方だけを変えてください。両方変えてはいけません。そうしなければどちらの変更が効いたのか分かりません。
設定を明示的な契約として扱う
size と n は出力とコストの両方に影響します。リテラルを各呼び出し箇所に通すのではなく、設定オブジェクトに固定してください。そうすれば機能全体のアスペクト比を変えるのは 1 回の編集で済みます。比較用に複数の画像が必要なら、複数回に分けるのではなく 1 回の呼び出しで要求してください。往復が減り、ログも読みやすくなります。
プロンプトを出力と一緒に保存する
生成された各画像のそばに、正確なプロンプト文字列、設定、モデル識別子を永続的に保存してください。再現できないプロンプトは、再生成もデバッグも改善もできない画像です。この一つの習慣が、どんなプロンプトのコツよりも時間を節約します。
比較のためにシードを設定する
同じプロンプトでも実行間で異なる画像が生成されることがあります。ある変更を評価するときは、単一の幸運な、あるいは不運なサンプルを信じるのではなく、集計結果(各設定で複数の画像)を比較してください。
プロンプトをバージョン管理する
プロンプトテキストをコードとして扱ってください。ファイルに保存し、変更をレビューし、どのプロンプトバージョンがどのアセットを生み出したかを記録します。これにより「先週火曜に画像が悪化したのはなぜか?」が答えられる問いになります。
本番投入前のチェックリスト
動作するリクエストは簡単な部分にすぎません。以下のチェックがデモと統合を分けます。
- すべての呼び出しにタイムアウトを設定する。 接続タイムアウトと読み取りタイムアウトを明示的に設定し、デフォルト値を決して使わないでください。読み取りタイムアウトのない生成エンドポイントは、いずれワーカーをハングさせます。
- 上限付きリトライ、リトライ可能なエラーだけをリトライする。 試行回数を制限し、ジッターを加え、検証と認証の失敗がリトライ経路を完全に迂回するようにしてください。
- キー管理。 キーは環境またはシークレットストアから読み取り、ソースからは決して読み取らないでください。コード変更なしでローテーションできるようにします。
- 構造化ログ。 モデル識別子、プロンプト(またはそのハッシュと参照)、設定、HTTP ステータス、試行回数、レスポンス内のリクエスト識別子を記録してください。これらがなければ、画像の問題は再現できません。
- コストの可視性。 生成は出力に応じて課金されるため、使用量は要求する画像数とリトライ頻度に依存します。リクエストがユーザーごと、タスクごと、バックグラウンド実行のどれかを事前に決め、それに応じて量を追跡してください。ハードコードされた仮定ではなく、ウェブサイト上のリアルタイムの価格パネルを確認して現在の料金を把握してください。
- 失敗時の挙動を定義する。 最終試行後に生成が失敗したときユーザーが何に遭遇するかを決めてください。エラー状態、プレースホルダー、あるいはキュー再試行か。未定義のフォールバックは未定義のユーザー体験になります。
- ペイロードスキーマを固定する。 依存するレスポンスフィールドを保存し検証してください。そうすればペイロードの変化は静かな
Noneではなく明示的なエラーとして現れます。
最終検証ステップ
curl コマンド、Python 関数、そして意図的に壊したリクエスト(まず壊れたキー、次に壊れたパラメータ)を実行し、それぞれが期待どおりの失敗を生み出すことを確認してください。この最後のステップが、エラー処理が本物か装饰的かを教えてくれます。
リクエストが認証済み、移植済み、適切にリトライされ、ログに記録されたなら、この統合はアプリの残りの部分の後ろに置くことができます。