チュートリアル
HiAPI API で qwen-image-3.0-pro/image-to-image を呼び出す方法:curl、Python、そして実際に動くリクエスト
非同期タスクパターン、curl と Python クライアント、エラー処理を網羅した統合演習
このページの内容
なぜ画像生図(image-to-image)が非同期タスクなのか
画像生図モデルを呼び出すとき、あなたは数百ミリ秒でストリーミング返却される文字列補完結果を求めているわけではない。モデルはソース画像を読み込み、それを条件として完全な拡散型生成プロセスを実行し、出力をエンコードする必要がある。これには数秒から数十秒かかり、その長さは解像度や設定によって変動する。その間ずっと HTTP 接続を開いたままにするのは、どの当事者にとっても割に合わない:プロキシはタイムアウトし、ロードバランサはアイドルソケットを破棄し、あなた自身のワーカースレッドも、後で失敗するかもしれないリクエストに縛り付けられる。
そのため、このエンドポイントは「まず送信、次にポーリング」モデルを採用している。最初のリクエストはタスクを送信し、すぐにタスクハンドルを返す。画像生成はそのハンドルの裏で進む。その後、独立した低コストのリクエストを送ってタスク状態を確認し、完了と報告された時点で、レスポンスが要求した結果を運んでくる。
これにはいくつかの実践的な帰結があり、設計の初期段階から織り込むべきだ:
- 送信は完了ではない。 送信呼び出しの成功は、プラットフォームがあなたのタスクを受け付けたことだけを意味する。コードではこの二つの状態を区別すること。
- タスク ID が唯一のハンドルだ。 永続化して保存すること。プロセスが送信とポーリングの間でクラッシュした場合、タスク ID があれば同じ作業を再送信(そして再課金)せずに復旧できる。
- ポーリングは低コストだが無料ではない。 状態確認は軽量だが、タイトなループはなおトラフィックを生み、レート制限を引き起こす可能性がある。間隔を空けること。
- 失敗は非同期に到着する。 壊れた画像や拒否されたパラメータは、送信時の HTTP エラーではなく、タスクレベルのエラーとして現れることがある。ポーリングコードはステータスコードだけでなく、タスクの状態も読まなければならない。
このモデルを覚えておけば、以降の統合は straightforward だ:1 回の呼び出しで作業を作成し、ループでそれを待ち、起こりうる三つのケースに対して意図的な処理を行う。
コードを書く前に:何を準備するか
ターミナルに触れる前に、本ガイドのすべての呼び出しが依存するいくつかのものを集めておこう。
HiAPI の認証情報
HiAPI の API キーが必要だ。秘密情報として扱うこと:コミットするかもしれないスクリプトに貼り付けるのではなく、環境変数から読み込む。以下の例では HIAPI_API_KEY として読み込む。API のベース URL と、正確なモデル識別子 qwen-image-3.0-pro/image-to-image が、全体を通じて参照する二つの定数だ。
ソース画像
画像生図には入力が必要だ。一枚用意し、どのように提供するかを決める:
- 公開アクセス可能な URL として、または
- アップロード済みアセットやエンコード済みペイロードとして(エンドポイントがどちらの形式を受け付けるかによる)。
呼び出しを書く前に、モデルのリクエストスキーマを調べて、正確なフィールド名と受け付けられるソース画像形式を確認すること。エンドポイントが受け付けないソース画像を提供することは、タスクが拒否される最も一般的な原因であり、事前に排除する方がエラーメッセージからデバッグするよりもはるかに簡単だ。
ポーリングできるクライアント
呼び出しが非同期であるため、リクエストを送るツールは後続のリクエストを繰り返し発行できる必要もある。curl は最初のスモークテストに適している;それ以上の用途はスクリプトであるべきだ。設定すべきコールバック URL も、ホストすべき webhook もない——ポーリングがメカニズムなので、ループを計画すること。
結果を確認する場所
あなたにとって「完了」がどのような形かを事前に決めておく:ブラウザで開ける URL か、ディスクに書き込むバイト列か。これを始める前に知っておけば、統合が実際に動いたときに一目でわかる。
これら四つが手元にあれば、最初のリクエストは短くなる。
curl で一度動くリクエストを送る
キー、エンドポイント、タスクライフサイクルがすべて機能することを確認する最速の方法は、2 ステップの curl セッションだ。まず送信し、次にポーリングする。
ステップ 1:タスクを送信する
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
項目ごとの説明:
-X POST—— 送信は作成操作だ。Authorizationヘッダーがキーを運ぶ。インラインで入力するのではなく環境変数をエクスポートすることで、シェル履歴に残るのを避けられる。Content-Type: application/json—— ボディは JSON だ。-d—— JSON ペイロード。imageフィールドはソース画像を指し、promptは実行する変換を記述する。パラメータ名と受け付けられるオプションはモデルのリクエストスキーマから来る;推測せず、そこで確認すること。
送信成功のレスポンスはタスクオブジェクトだ。識別子——タスク ID と呼ぶ——と、タスクがキューに入ったか実行中であることを示すステータスフィールドを含む。タスク ID をメモすること;以降のすべてがそれに依存する。
ステップ 2:タスクをポーリングする
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
各呼び出しでステータスフィールドを読む。保留中または実行中と報告されたら、数秒待ってから再確認する。成功と報告されたら、レスポンスには生成された画像が含まれる——通常は取得可能な URL、またはエンコードされたデータだ。失敗と報告されたら、レスポンスは理由を説明するエラー記述を運ぶ。
ライフサイクルはこれだけだ:1 回の送信、そして終端状態までの状態確認。以降に構築するものはすべて、これら二つのコマンドのより便利なバージョンに、待機とエラー処理を加えたものにすぎない。
Python で同じ呼び出しを実装する
この 2 つの curl ステップを手作業で繰り返すのはすぐに面倒になるし、ポーリングループを各スクリプトにコピペするのは、微妙なバグが広がるまさにその方法だ。送信とポーリングのパターンを再利用可能な関数に包み込もう。
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
いくつかの意図的な選択を指摘しておく価値がある:
- 送信と待機を分離する。 送信が失敗すれば、ポーリングが始まる前にわかる。将来、あるプロセスで送信し別のプロセスで収集したければ、その継ぎ目はすでに存在する。
- すべてのリクエストに
timeoutがある。 タイムアウトのないリクエストは無期限にハングする可能性があり、それはまさに非同期 API が避けるべき失敗モードだ。 - ポーリングループには間隔と全体の締め切りの両方がある。 締め切りがなければ、実行中のままスタックしたタスクは永遠にループする。間隔がなければ、エンドポイントを猛連打することになる。
- ステータス文字列は明示的に照合される。 成功でも失敗でもない状態は次のイテレーションに落ちるが、これは中間状態に対して正しいデフォルト動作だ。
他の関数と同じように呼び出せばよい:generate(source_url, "make the background a dusk cityscape")。返されるオブジェクトは終端状態のタスクペイロードで、そこから画像参照を抽出する。
エラーと失敗したタスクの処理
非同期ワークフローのエラーは三つのカテゴリに分かれ、それぞれ異なる対応が必要だ。
リクエストレベルの拒否
これらは送信呼び出しの通常の HTTP エラーレスポンスだ——認証情報の誤りや欠如、JSON の形式エラー、サポートされないパラメータ、アクセスできないソース画像。タスクが存在する前に到達する。
正しい対応はほぼ常に停止してメッセージを提示することだ。形式エラーのペイロードをリトライしても、クォータと時間を浪費するだけだ。ステータスコードとレスポンスボディを逐語的に記録すること;検証メッセージは通常、問題のあるフィールドを指し示す。特別に扱う価値のあるケースが二つある:認証失敗は設定の問題を意味するので、素早く且つ大きく失敗させるべきだ;レート制限レスポンスはバックオフ後にリトライできる。
タスクレベルの失敗
ここでは送信は成功し、タスク ID は存在するが、作業が失敗した。ポーリングレスポンスは失敗ステータスとエラーを報告する。
このカテゴリはモデル自体の問題をカバーする:ソース画像はデコードできるが使用不可、プロンプトが拒否された、生成が内部制限に達した。これらは入力に特有のものなので、盲目的なリトライは通常同じ失敗を再現する。ケースごとに判断すること:一時的な内部エラーは一度リトライする価値があるかもしれない;拒否されたソース画像は決して価値がない。タスク ID をエラーと一緒に記録し、サポート依頼と関連付けられるようにすること。
終わらないポーリング
送信は成功し、タスクは存在し、ポーリングは実行中——しかし終端状態が決して到達しない。これはプラットフォームが返すエラーではない;あなたのコードの中の、期限切れにしなければならない仮定だ。
Python の例に示すように、締め切りでこれを防ぐこと。締め切りが発火したら、ポーリングを停止する。半完成の結果を黙って返してはいけない;明示的なタイムアウト結果を投げるか返し、呼び出し側に判断を委ねること。タスク ID を保持すること——タスクはあなたの締め切り後に完了している可能性があり、再送信せずに後で収集したいかもしれない。
これら三つのカテゴリに対する実用的な経験則:タスク状態を唯一の信頼できる情報源として扱うこと。HTTP ステータスコードはリクエストが受け付けられたかを伝え;タスクの状態とエラーフィールドは作業が成功したかを伝える。両方を読めば、失敗は謎ではなく診断可能になる。
プロダクションコードに組み込む
上記の関数は動作する統合であり、完成したサービスではない。実際のトラフィックを支える前に、四つのことを引き締める必要がある。
至る所にタイムアウト
すべての呼び出しに明示的な接続と読み取りのタイムアウトを設定する——送信、ポーリング、そして結果画像の後続取得も含めて。さらに、タスクライフサイクル全体に対する全体の締め切りを設定する。HTTP 層のタイムアウトは個々のリクエストを守り;タスクの締め切りは操作全体を守る。
判断力のあるリトライ
安全にリトライできるものだけをリトライする。ポーリング時のレート制限や一時的なネットワークエラーは条件を満たす。拒否されたペイロードは満たさない。タスクレベルの失敗では、リトライは新しいタスクの送信を意味し、これは状態確認のリトライとは異なり、より高コストな操作だ——意図的な決定として扱い、できれば上限を設けること。
タスク ID を含むログ
送信時およびその後の各状態遷移時に、時間情報とともにタスク ID をログに記録する。送信から最初の終端状態までの間隔は、物事が遅く感じられるときに実際に欲しくなる指標だ。ユーザーが悪い結果を報告したとき、タスク ID は逸話を追跡可能な記録に変える鍵だ。
ポーリングをリクエストパスから遠ざける
関数が Web ハンドラ内で実行される場合、同期ポーリングループは生成時間全体にわたってリクエストを開いたままにする——これはまさに非同期設計が避けようとする問題だ。代わりに、ハンドラで送信し、タスク ID を呼び出し側に返し、待機はバックグラウンドワーカー、キュー、またはスケジュールされたタスクで実行すること。そうすればクライアントはモデルではなくあなたのサービスをポーリングする。
この順序で構築すれば、統合は「自分のマシンでは動く」から、依存できるものへと変わる:送信し、ハンドルを永続化し、制限付きで待ち、希望ではなくタスク状態にいつ停止すべきかを教えてもらう。