チュートリアル

Qwen Image 3.0 API の使い方？中国語ポスターを一発で正しく生成

通義千問画像 3.0 の4つのエンドポイントのパラメータ、curl と Python（先に画像生成、その後画像編集）、料金、そして旧形式がなぜエラーになるのか。

Oct 18, 2026

TL;DR

Qwen Image 3.0（通義千問画像 3.0）は HiAPI 上に4つのエンドポイントがあります：標準版 qwen-image-3.0/text-to-image、qwen-image-3.0/image-to-image、Pro 版 qwen-image-3.0-pro/text-to-image、qwen-image-3.0-pro/image-to-image。モデルページを開くとオンラインで試せます。
標準版は定額で1枚あたり $0.0358（1K、2K 同価格）。Pro は 1K $0.0497、2K $0.0993。画像編集と画像生成は同価格で、参照画像1〜3枚でも追加料金なし。
中国語および中英バイリンガルの文字が得意分野。呼び出し方：POST /v1/tasks に prompt、aspect_ratio、resolution を渡し、success になるまでポーリングしてからダウンロードします。

まず1枚見てみましょう

標準版、16:9、看板の中国語を一文字ずつ正しく生成：

qwen-image-3.0/text-to-image、16:9、$0.0358。

パラメータ早見表

フィールド	必須	値	説明
`prompt`	はい	最大 18000 文字	出現させたい文字を一文字ずつ引用符で囲んで書く
`aspect_ratio`	いいえ	`1:1`（デフォルト）`3:2` `2:3` `4:3` `3:4` `16:9` `9:16` `21:9`
`resolution`	いいえ	`1K`（デフォルト）/ `2K`	標準版は2段階とも同価格、Pro は 2K が倍額
`output_format`	いいえ	`png`（デフォルト）/ `jpeg`
`prompt_extend`	いいえ	ブール値、デフォルト `true`	プロンプトを自動書き換え；文字を正確に指定したいときはオフ
`negative_prompt`	いいえ	最大 500 文字	出現させたくない内容
`seed`	いいえ	0–2147483647	固定すると再現しやすい
`image_urls`	画像編集エンドポイントでは必須	1〜3 枚	JPEG、PNG、WEBP など、1枚あたり 10 MB 以下

パラメータは厳密に検証され、余分なフィールドを渡すと 400 が返ります。注意：旧形式の "model": "qwen-image-3.0" に size を加える書き方はもう使えず、「模型不可用」または additional properties 'size' not allowed が返ります。上記のモデル名と aspect_ratio + resolution に変更してください。

curl：最初の1枚を動かす

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "秋季ドリンクのポスター、中央に桂花ラテのカップ、上部に大きな見出しで「秋日限定」と一文字ずつ書き、下部にサブタイトルで「桂花ラテ」と書き、余白を十分に取り、柔らかな自然光",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

レスポンスに data.taskId が含まれます。GET /v1/tasks/{taskId} をポーリングし、status が success になったら output[0].url からダウンロードします。標準版は 2K と 1K が同価格なので、そのまま 2K を指定しましょう。

Python：まず画像生成、次に画像編集

# pip install requests; export HIAPI_KEY=あなたの Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 同じ送信をリトライするときは同じ Idempotency-Key を再利用し、課金は1回だけ
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# テキストから画像生成、標準版 2K（$0.0358）
poster = run("qwen-image-3.0/text-to-image",
             prompt="お茶ギフトボックスの商品画像、クラフト紙の四角い箱の正面に「云雾绿茶」と書き、下部に小さく「净含量 100 克」と書き、石板の天板、柔らかなトップライト",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# 画像編集：背景を濃い色に変更、文字はそのまま（同じく $0.0358）
edited = run("qwen-image-3.0/image-to-image",
             prompt="ギフトボックスとその上の文字を完全にそのまま保持し、背景を深い墨緑色のベルベットに変更し、サイドライトを一筋加える",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

Pro に切り替えるにはモデル名だけ変更：qwen-image-3.0-pro/text-to-image または qwen-image-3.0-pro/image-to-image、パラメータは完全に同じです。

料金

エンドポイント	1K	2K
標準版テキストから画像 / 画像編集	$0.0358	$0.0358
Pro テキストから画像 / 画像編集	$0.0497	$0.0993

HiAPI 現行価格、2026 年 10 月 18 日確認。失敗時は課金されません。

2段階の同一プロンプトでの比較は Qwen Image 3.0 API 価格をご覧ください。

公開前の注意点

文字を正確に指定したいときは prompt_extend をオフ：デフォルトではプロンプトが書き換えられ、指定した文字が勝手に変更されることがあります。
出現させたい文字は一文字ずつ引用符で囲んで書き、「上記の文字以外は他の文字を入れないでください」という一文を加えましょう。
ポーリングの代わりにコールバックを使用：input と同じ階層に "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"} を加え、taskId で重複排除します。
Idempotency-Key リクエストヘッダーを付ける：リトライ時、同じ Key ならタスクは1回だけ作成されます。
結果はすぐにダウンロード：output[0].url には有効期限があります。