チュートリアル
HiAPI API 経由で qwen-image-2.0-pro を使う方法:curl、Python、そして一度で成功するリクエスト
開発者向けの実践的な統合演習:初回の成功呼び出し、リクエスト構造の解剖、トラブルシューティング
このページの内容
qwen-image-2.0-pro が API 利用者に提供するもの
qwen-image-2.0-pro は HTTP 経由で呼び出す画像生成モデルです。コードから見ると、その振る舞いはチャット補完エンドポイントに似ています。欲しい画像を記述した JSON ペイロードを送信すると、生成された画像を含む JSON レスポンスを受け取ります。
HiAPI API 経由でアクセスする利点は一貫性にあります。1 つの API キー、1 つのベース URL、1 つのリクエスト構造がモデルをまたいで共通に使えます。後でモデル識別子を変更したりパラメータを調整したりしても、周辺のコードはそのままです。試す画像モデルごとに新しい SDK を学んだり、複数の資格情報を管理したりする必要はありません。
このチュートリアルでは、まず curl で初回呼び出しを一度完全に完了させ、それを Python に移植し、レスポンスから画像を取り出す方法を説明し、最後にトラブルシューティングのチェックリストと小さな再利用可能なラッパーを示します。すべての例が同じペイロードと同じキーの環境変数を使うため、ターミナルで動いた内容はスクリプトでも変更なしに動作します。
前提条件とキーの準備
コードを書き始める前に、次の 3 つが整っていることを確認してください。
1. HiAPI アカウントと API キー
アカウントを作成し、ダッシュボードで API キーを生成します。キーは機密情報であり、パスワードと同様に扱ってください。バージョン管理にコミットされるソースファイルに貼り付けないでください。
2. キーを環境変数としてエクスポートする
以下の例は HIAPI_API_KEY からキーを読み取るため、同じコマンドやスクリプトがローカルでも CI でも変更なしに動作します。
export HIAPI_API_KEY="your_key_here"
Windows PowerShell では $env:HIAPI_API_KEY = "your_key_here" を使用します。CI では、パイプライン設定のシークレット環境変数として設定します。
3. HTTP リクエストを送信するためのツール
curl は通常プリインストールされています。Python では Python 3 と requests ライブラリが必要です。
pip install requests
先に進む前に、シェルからキーが見えることを確認できます。
# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."
何も出力されない場合、変数が設定されていないため、すべてのリクエストが認証エラーで失敗します。まずこれを解決してください。
curl による最小限の動作するリクエスト
接続性を確認する最速の方法は、環境変数からキーを読み取る curl 呼び出しを実行することです。ペイロードは model フィールドとチャット補完スタイルの messages 配列を含む JSON オブジェクトです。
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "木製のテーブルの上に置かれた小さな陶器のマグカップ、柔らかな朝の光、商品写真"
}
]
}'
ここでは 3 つの細部が重要です。Authorization ヘッダーは Bearer スキームを使います。model の値はモデル識別子と完全に一致しなければなりません。content は画像を説明するプレーン文字列のプロンプトです。
リクエストが成功すると、ターミナルに出力された JSON レスポンスが表示されます。失敗すると、HTTP ステータスコードとエラーメッセージが表示されます。レスポンス本文を読む前にステータスコードを確認してください。401 はキーが誤っているか欠落していることを示し、400 は通常ペイロードの形式が誤っていることを示し、404 またはモデル未検出エラーはモデル識別子が正しくないことを示します。
このコマンドが成功レスポンスを返せば、接続性が正常であることが確認でき、コードの記述に進めます。
Python での同じリクエスト
呼び出しを Python に移植する際は、ペイロードをまったく同じに保ちます。唯一の違いは、環境変数の読み取り方法とリクエストのシリアライズ方法です。
import json
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "木製のテーブルの上に置かれた小さな陶器のマグカップ、柔らかな朝の光、商品写真",
}
],
}
response = requests.post(
"https://api.hiapi.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))
json=payload により requests が Content-Type ヘッダーを自動設定し、リクエスト本文をシリアライズすることに注意してください。timeout は重要です。画像生成は典型的なテキスト補完よりも時間がかかる場合があり、120 秒は妥当な出発点です。raise_for_status() はエラーステータスコードを例外に変換するため、失敗が黙って見過ごされることはありません。
このスクリプトを実行すると、curl で見たのと同じ JSON が得られるはずです。得られない場合、環境が curl が成功したシェルと異なっています。最も多いのはキー変数です。
レスポンスを読み取り、画像出力を処理する
レスポンスはチャット補完の構造に従うため、生成された画像はテキスト応答を処理するのと同じ経路で取得されます。まず出力された JSON を確認してください。その構造は見慣れたものです。
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
生成された画像はアシスタントメッセージの内容に現れ、通常はモデルがメディアを返す方法に応じて URL または base64 エンコードされたペイロードとして表されます。どちらであるかを仮定せず、値を読み取ってその接頭辞に応じて分岐してください。
content = data["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
image_url = content
# Download and save if you want a local copy
image_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from URL")
else:
# Treat as base64-encoded image data
import base64
image_bytes = base64.b64decode(content)
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from base64")
実用的な注意点が 2 つあります。内容が URL の場合、それを一時的なリンクとして扱い、製品内で直接リンクするのではなく速やかにダウンロードしてください。base64 の場合、デコード処理を分離して、形式が誤ったペイロードが捕捉可能なエラーを投げるようにしてください。解析の前に必ず生のレスポンスをログファイルに書き出しておけば、遅い可能性のあるリクエストを再実行せずにデバッグできます。
失敗したリクエストのトラブルシューティングチェックリスト
リクエストが失敗したとき、呼び出し全体を慌てて書き直さないでください。以下のチェックを順番に実行し、最初に失敗した箇所で止めます。各チェックは 1 つの変数を切り分けます。
1. 認証
まずステータスコードを確認します。401 はキーが欠落、期限切れ、または形式が誤っていることを示します。現在のシェルで環境変数が設定されていること、Bearer プレフィックスを使用していること、ヘッダーに末尾の空白がないことを確認してください。
2. モデル識別子
モデル未検出エラーは、model の値が利用可能なモデルと完全に一致しないことを示します。大文字小文字とサフィックスが重要です。値をモデルのドキュメントページと 1 文字ずつ照合してください。
3. ペイロード構造
400 は通常、形式が誤ったリクエスト本文に起因します。messages が配列であること、各メッセージに role と content が含まれること、JSON が有効であることを確認してください。送信前に jq や python -m json.tool でペイロードを処理すると、構文エラーを捕捉できます。
4. レスポンス処理
リクエストは成功したのにスクリプトがクラッシュする場合、問題は API ではなく解析コードにあります。スライスの前に生のレスポンス本文を記録し、読み取っているパスが実際に存在することを確認してください。画像はある呼び出しでは URL、別の呼び出しでは base64 で返ることがあるため、仮定せず内容に応じて分岐してください。
5. タイムアウトとリトライ
画像生成は遅くなることがあります。タイムアウトが発生した場合、クライアントのタイムアウト時間を増やして 1 回再試行してください。4xx エラーに対しては再試行を避けてください。同じように再び失敗するだけです。
有用な習慣として、既知の成功したリクエストのコピーを保存し、失敗したリクエストと比較してください。ほとんどの失敗は 1 つのフィールドだけが異なります。
再利用可能なクライアントとしてラップする
呼び出しが成功したら、小さな関数の背後にラップして、モデルとパラメータの変更を 1 か所に集約します。このラッパーはキーの取得、ヘッダー、エラー処理を一元管理します。
import base64
import os
import requests
HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"
def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
"""画像を生成し、その生のバイト列を返します。"""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
}
response = requests.post(
f"{HIAPI_BASE}/chat/completions",
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
return requests.get(content, timeout=60).content
return base64.b64decode(content)
呼び出しコードは 1 行になります。open("out.png", "wb").write(generate_image("木製のテーブルの上の陶器のマグカップ"))。後で別の画像モデルに切り替えたりパラメータを追加したりする場合、この関数だけを変更すれば済みます。モデル識別子とパラメータの詳細はモデルページにあり、qwen-image-2.0-pro のモデル詳細を確認してから接続できます。
まず curl 呼び出し、次に Python スクリプト、最後にラップです。各ステップは次の層を構築する前に、より小さな部分を確認します。