チュートリアル

Qwen Image 2.1 Turbo API の使い方：curl、Python、そして実リクエストの結果

Oct 24, 2026

Qwen Image 2.1 Turbo（qwen-image-2.1-turbo）は、hiapi 上で Alibaba の 2.1 画像シリーズの中でも高速かつ低価格なティアです。テキストプロンプトと、任意で 0〜10 枚の参照画像を受け取り、2048×2048 の PNG を 1 枚返します。本ガイドでは、そのまま実行できるリクエスト、API が実際に適用する入力スキーマ、1 回の編集呼び出し、そして「透明 PNG」という主張を検証した際に観測した結果を紹介します。

hiapi の API キーはコンソールから取得してください。呼び出しは統一された非同期タスク API を経由するため、同期的な画像レスポンスはありません。

最小リクエスト：テキストから画像生成

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "贴纸风格的插画：一只戴着草帽的柴犬坐在冲浪板上，平涂配色，粗轮廓线，珊瑚橙与海蓝色",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

その後 GET /v1/tasks/<taskId> をポーリングし、data.status が success になるまで待ってから data.output[0].url を読み取ります。

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # 注意：字段是 taskId，不是 id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # 临时网络错误：继续轮询同一个 id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

ファイルはすぐにダウンロードしてください。出力 URL は temp.hiapi.ai 上にあり、expireAt タイムスタンプが付いています（私たちの実行では作成から約 7 日後）。より長く保持する必要がある場合は、ファイルのバイト列を自分で保存してください。

入力スキーマ（API が実際に適用するルール）

以下は、私たちが故意に無効なリクエストを送った際に返された検証エラーに基づく内容であり、ドキュメントの言い換えではなく、オンラインエンドポイントの実際の挙動を反映しています：

フィールド	ルール
`prompt`	必須の文字列（モデルページのフォームでは上限が 4500 文字に設定されています）
`aspect_ratio`	`1:1`、`16:9`、`9:16`、`4:3`、`3:4` のいずれか
`image_urls`	参照画像 URL の配列、0〜10 項目。文字列を直接渡すと拒否され、`image_urls must be an array` が返ります
`prompt_extend`	ブール値、プロンプト最適化のオン/オフ
`seed`	整数、0 から 2147483647

同シリーズの他の Qwen モデルとは異なる点が 2 つあります。ここにはresolution フィールドがありません。このフィールドを送信すると additional properties 'resolution' not allowed が返ります。1:1 の場合、出力は固定の 2048×2048 キャンバスであり、これは私たちが実測済みです。また、未知のフィールドは通常無視されるのではなく拒否されます。誤った aspect_ratio は HTTP 400 を返し、error_code: INVALID_REQUEST とともに、message に許可される値が列挙されます。

参照画像を使った編集

編集とスタイル再描画は同じモデル id を使用します。元画像を image_urls に入れ、プロンプトで変更内容を記述します：

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "把草帽重新着色为深紫色，其他部分保持不变",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

実運用で観測した結果

私たちは 2026-10-24 に、テキストから画像生成の呼び出しと編集の呼び出しを 1 回ずつ実行し、いずれも seed: 42、aspect_ratio: "1:1" を使用しました。

レイテンシ：テキストから画像生成は作成から約 29 秒で success に達しました（タスクの created から completed までのタイムスタンプ）。編集は約 22 秒かかりました。ステータスは success になる前に数回のポーリングで archiving を経由するため、非終端状態をエラーと見なさないでください。これは 2 サンプルに過ぎず、ベンチマークではありません。
出力：どちらも 2048×2048 の PNG を返し、テキストから画像生成の結果は約 3.9 MB でした。
編集の挙動：最初の出力を再入力し、帽子を紫色にするよう要求しました。結果は犬、姿勢、波、レイアウトを保持し、帽帯とリボンを紫色寄りにしましたが、帽子の草編みの本体はほぼ草色のままでした。テクスチャのある物体の色変更では、編集の指示追従度は部分的にしか効かないことがあるため、プロンプトは「帽帯を再着色する」のように具体的に書くべきで、曖昧な表現は避けてください。
透明背景：アルファチャネルは完全に不透明です。モデルページでは透明背景 PNG を出力できると宣伝されており、私たちはプロンプトに「完全な透明背景、被写体と飛沫効果のみを保持」と書きました。返されたファイルは RGBA でしたが、すべてのピクセルの alpha は 255（透明ピクセルはゼロ）で、四隅は薄いグレーホワイト（例：(241, 243, 248, 255)）でした。画像を確認すると、モデルはそれらのピクセルを透明のままにするのではなく、淡いチェッカーボード風の背景をピクセルに描き込んでいました。編集出力も同様でした（最小 alpha は 241）。したがって私たちの実行では、プロンプトだけではカラーページにそのまま置ける切り抜き画像は得られませんでした。この結果は 1 つのプロンプトの書き方に対応するものに過ぎません。私たちは透明度を切り替えられるリクエストフィールドを見つけられませんでした（transparent は未知の属性として拒否されます）。真のアルファチャネルが必要な場合は、851-labs 背景除去ガイドを参考にするなど、背景除去ステップを計画し、公開前に Image.open(f).getchannel("A").getextrema() のようなピクセルチェックで検証してください。

本番環境での注意点

高並列時はポーリングの代わりにコールバックを使用：タスクのリクエストボディに "callback": {"url": "https://your.app/hook", "when": "final"} を追加し、コールバックはヒントとして扱い、GET /v1/tasks/<taskId> で結果を確認してください。
taskId を保持：ポーリングがネットワークエラーで失敗した場合、再送信するのではなく同じ id を再ポーリングしてください。再送信すると 2 つ目のタスクが作成され、課金されます。
seed を固定して、プロンプトを調整する際に比較可能な出力を得てください。これはベストエフォートであり、厳密な保証ではないとお考えください。
課金前に検証：スキーマエラー（HTTP 400、INVALID_REQUEST）は作成時に返され、その時点ではまだ画像は生成されていません。

どのティアを選ぶか

同じシリーズには Qwen Image 2.1 Pro もあり、料金ページでは 1 枚あたりの価格が Turbo より高いと表示されています。どちらもテキストから画像生成、編集、0〜10 枚の参照画像をサポートすると説明されていますが、私たちは Turbo しか実行していないため、相対的な画質については何も断言しません。Turbo の利点はより低い価格と 8 ステップの速度にあります。素材で出力品質をより重視する場合は、同じプロンプトと seed で両方をそれぞれ実行して比較してください。より新しい Qwen 3.0 世代については、Qwen Image 3.0 API ガイドと Qwen Image 3.0 Pro ガイドを参照してください。