チュートリアル
hiapi で curl と Python を使って minimax-h3-image の画像から画像を生成する方法
このページの内容
画像から画像への生成エンドポイントが期待するもの
コードを書く前に、画像から画像への生成呼び出しの構造を理解しておくと役立ちます。minimax-h3-image の画像から画像への生成エンドポイントは、参照画像(1 枚または複数枚)とテキストプロンプトを受け取り、プロンプトに従いつつ参照画像にアンカーされた新しい生成結果を返します。
概念的には、各リクエストは 3 つの部分で構成されます:
- モデルルーティング——
image-to-imageタスクを通じてminimax-h3-imageを指定し、すべて単一の hiapi エンドポイント経由で完結します。能力ごとに個別の認証情報やホストを用意する必要はありません。 - 入力——プロンプト文字列、1 枚以上の参照画像(URL または base64 ペイロード)、および解像度ティアなどの生成制御項目。
- 出力契約——呼び出しは非同期です。タスク識別子を受け取り、その後ステータスをポーリングし、タスク完了時に生成された画像 URL を取得します。
最後の点は重要です。画像から画像への生成は、同じレスポンス内でピクセルを返すブロッキング呼び出しではありません。送信呼び出しは「ジョブをキューに入れる」ものとみなし、最初からタスクのライフサイクルを中心にクライアントを設計してください。同期動作を前提に設計すると、後で統合コードを書き直すことになります。
すべてが同じ hiapi インターフェースを経由するため、リクエストヘッダー、認証、レスポンスのラッピングはモデルやタスク間で一貫しています。minimax-h3-image で一度覚えれば、同じパターンがプラットフォーム上の他の場所にも当てはまります。
最小の実行可能なリクエスト
認証情報、エンドポイント、ペイロード構造が正しいことを証明する最小のリクエストから始めてください。最初からすべてのオプションフィールドを追加しようと急がないでください。
最小のリクエストボディには以下が含まれます:
- モデル名
minimax-h3-image - タスクタイプ
image-to-image - どのような変換を望むかを記述した
prompt - 単一の参照画像フィールド
- 解像度ティア
概念的には、ペイロードは概ね次のようになります:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "このスケッチを白背景上のクリーンな製品レンダリング画像に変えてください",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
これを送信し、タスク id が返されることを確認してから、手動で 1〜2 回ポーリングして状態遷移を観察してください。タスク id が取得できれば、接続性と認証は問題なく、実際のクライアント構築に進めます。取得できなければ、エラーレスポンスボディを読んで停止してください——通常は問題のあるフィールドを直接指し示してくれます。
このリクエストをスモークテストとして保存してください。後の変更でパイプラインが壊れたとき、この最小リクエストを再実行すれば、問題がペイロードにあるのか周辺コードにあるのかを即座に教えてくれます。
curl での呼び出し
curl は生のリクエストとレスポンスを確認する最速の方法です。JSON ボディをファイルに書き出せば、編集時にシェルのクォートと格闘せずに済みます。
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "この写真を水彩イラスト風に変えてください",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
2 つのヘッダーが主な役割を担います:ベアラートークン付きの Authorization と Content-Type: application/json です。どちらもバージョン管理から遠ざけてください——キーは環境変数から読み取り、コマンドに貼り付けないでください。
送信が成功したら、返されたタスク id を取得してポーリングします:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
レスポンスにはステータスフィールドがあり、完了後には結果があります。jq を使って必要なフィールドだけを抽出します:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
これはペイロードのデバッグにも最も簡単な方法です:curl は何を送信し何が返されたかを正確に表示し、クライアントライブラリに何も隠されません。
Python での呼び出し
Python 版は curl の流れを鏡映すべきです:送信、id の取得、終端状態までポーリング、結果の取得。requests と Session を使い、接続の再利用とデフォルトヘッダーを一度だけ処理します。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"タスク {task_id} は {timeout} 秒以内に完了しませんでした")
if __name__ == "__main__":
task_id = submit(
"この画像をフラットベクターポスターに変えてください",
"https://example.com/reference.png",
)
print("送信済み:", task_id)
result = poll(task_id)
print(result)
重要な詳細:raise_for_status() は HTTP エラーを例外に変え、静かに失敗させません;ポーリングループには期限と間隔の両方があります;終端状態は明示的に判定されます。画像 URL は結果オブジェクトからステータスが終端状態に達した後にのみ解析し、決して早まらないでください。
複数の参照画像の使用
単一の参照画像では不十分なことがよくあります。ある写真の顔を保ちつつ、別の写真の構図を借りたり、質感と輪郭を融合させたりしたい場合があります。minimax-h3-image の画像から画像への生成は、複数形の image フィールドを通じて複数参照入力に対応しています。
構造的には、input オブジェクトは単一の参照画像を image フィールドで、複数ある場合は images 配列で保持できます:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "最初の画像の人物を保ち、2 番目の画像の背景スタイルを使用してください",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
順序には意味があります。参照インデックス 0 が主要な対象で、後続の項目は補助的なコンテキストです。そのため、プロンプトの表現は送信する順序と一致させてください。結果が参照画像を無視している場合、通常の原因はフィールドの不具合ではなくプロンプトの曖昧さです——どの画像がどの属性を決めるのかをプロンプトで明確に述べてください。
複数参照の実用的なルール:
- 数は控えめに。 特定のプロンプトが本当に必要とする参照画像だけを使う;余分に追加すると制御力が薄れます。
- できるだけアスペクト比を揃えることで、モデルが矛盾する構図を調停する必要がなくなります。
- 同じリクエスト内では公開 URL または base64 を一貫して使う;転送方式を混在させないでください。
統合中に一度 2 画像リクエストを送信し、両方の参照画像が出力に明らかに影響していることを検証してから、その上により複雑なロジックを構築してください。
解像度ティアの選択
resolution フィールドは minimax-h3-image の画像から画像への生成で出力ティアを選択します。これは単なる見た目のノブではなく、計算量、応答遅延、そして最終的に扱うペイロードサイズを変えます。
トレードオフの考え方:
- 目標シーンを満たす最小のティアを選ぶ。 リスト表示用のサムネイルにはメインビジュアルバナーと同じティアは不要です。高解像度出力を後からダウンサンプリングするのは時間とお金の無駄です。
- 遅延は解像度とともに増えると予想する。 高いティアはリクエストごとにより多くの作業を行うため、ポーリングのタイムアウトと間隔の予算は選択したティアを反映すべきです。
- ペイロードサイズに注意する。 base64 参照入力と高解像度出力はどちらも転送量を増やします;大量の画像を扱う場合はリクエストとレスポンスのボディに注意してください。
課金はリクエストした解像度ティアに従います——リクエストは実行されたティアで課金されるため、小さなユースケースで過大なティアを使うと気づかないうちに多く支払うことになります。ハードコードした仮定ではなく、価格パネルのリアルタイム料率を確認してください。
合理的な統合戦略は:開発段階では速度のために中程度のティアを使い、プロンプトと参照画像セットが固まったら、重要なアセットをより高いティアに引き上げることです。解像度を後から変更すると遅延測定が無効になるため、実際に本番公開する予定のティアでベンチマークを取ってください。
非同期ライフサイクルの処理
hiapi 上のすべての画像から画像への生成呼び出しは同じループに従います:送信、タスク id の取得、終端状態までポーリング、そして結果の取得。このループを堅牢にすることが、本番品質クライアントの作業の大部分です。
送信して記録する
タスク id を永続的なハンドルとして扱ってください。送信レスポンスが届いたらすぐに、他の何よりも先に記録してください——プロセスがポーリング途中でクラッシュしても、この id があれば再生成せずに復旧できます。
バックオフ付きでポーリングする
固定 2 秒ポーリングはインタラクティブな使用には問題ありませんが、長いバッチには無駄です。短い間隔から始めて徐々に増やし、最大間隔に上限を設けることで、完了を適時に検出できます。
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
終端状態を尊重する
成功または失敗のときだけループを抜けてください。空でないレスポンスをすべて「完了」とみなすのは最も一般的な非同期バグです——まだ存在しない結果を読むことになります。
すべてに境界を設ける
各 HTTP 呼び出しにタイムアウトを設定し、タスクに全体的な期限を設けてください。期限が過ぎたら、空回りし続けるのではなく明確なエラーを投げてください。一時的なネットワークエラーに対しては、バックオフ付きでポーリングを再試行してください;盲目的に再送信すると重複作業を引き起こします。
クリーンアップ
結果を取得したら、画像 URL またはバイトを自分のストレージに速やかに永続化してください。タスク結果は一時的なハンドルであり、アプリケーションの長期的な CDN ではありません。
トラブルシューティングと本番チェックリスト
開発者が minimax-h3-image の画像から画像への生成を使うとき最初に遭遇する失敗と、それを防ぐチェック項目です。
初回実行の失敗
- 401 / 403——ベアラートークンが欠落、期限切れ、または前後に空白文字が含まれています。リクエストを実行するシェルで環境変数がエクスポートされていることを確認してください。
- 422 または検証エラー——エラーレスポンスボディを確認してください;通常はフィールドを指し示します。よくある原因は
promptをinputの内部ではなくトップレベルに置いていることです。 - JSON 形式エラー——送信前に
jq .でペイロードファイルを検証してください。
実行時の失敗
- タスクが永遠に完了しない——ポーリングにプレースホルダーではなく実際に受け取った id を使用していることを確認してください。期限が選択した解像度ティアに対して十分長いか確認してください。
- 「完了」タスクの結果が空——ステータスフィールドを正確に読んでください;失敗ステータスもレスポンスボディを返します。
- 参照画像が無視される——モデルを責める前に、プロンプトの表現と参照画像の順序を再確認してください。
公開前チェックリスト
- API キーとベース URL は環境変数から読み取り、決してリポジトリにコミットしない。
- 各 HTTP 呼び出しに明示的なタイムアウトがある。
- ポーリングは有界バックオフを使用し、厳格な全体期限を持つ。
- 終端状態は明示的に処理され、結果解析ブランチに落ちない。
- 結果はアプリケーションがダウンロードして保存し、タスクレスポンスからのホットリンクではない。
- 複数参照プロンプトはどの画像がどの属性を制御するかを明記している。
- 解像度ティアは本番公開予定の値でベンチマーク済み。
- ログにタスク id を記録し、失敗ジョブを追跡・復旧できる。
問題が発生するたびに、前述の最小リクエストを再実行してください——問題がペイロードにあるのか周辺コードにあるのかを切り分けられます。リクエスト構造、curl と Python クライアント、複数参照処理、そして規律あるポーリングループがあれば、hiapi 上で minimax-h3-image の画像から画像への生成を確実に本番公開するために必要なすべてが揃います。