aliyun-qwen-image

Category: provider

Model Studio Qwen Image

検証

mkdir -p output/aliyun-qwen-image
python -m py_compile skills/ai/image/aliyun-qwen-image/scripts/generate_image.py && echo "py_compile_ok" > output/aliyun-qwen-image/validate.txt

合格基準：コマンドが終了コード 0 で終了し、output/aliyun-qwen-image/validate.txt が生成されること。

出力と証跡

• 生成した画像の URL、プロンプト、メタデータを output/aliyun-qwen-image/ に書き込みます。
• 実行ごとに、サンプルの JSON レスポンスを 1 つ以上保存します。

動画エージェントパイプラインで一貫した画像生成動作を実現するため、image.generate の入出力を標準化し、DashScope SDK（Python）を使用して正確なモデル名を指定します。

前提条件

• SDK をインストールします（PEP 668 による制限を避けるため、venv の使用を推奨します）。

python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashscope

• 環境に DASHSCOPE_API_KEY を設定するか、~/.alibabacloud/credentials に dashscope_api_key を追加します（環境変数が優先されます）。

重要なモデル名

次のいずれかのモデル文字列を正確に使用してください。

• qwen-image
• qwen-image-plus
• qwen-image-max
• qwen-image-2.0
• qwen-image-2.0-pro
• qwen-image-2.0-2026-03-03
• qwen-image-2.0-pro-2026-03-03
• qwen-image-max-2025-12-30
• qwen-image-plus-2026-01-09

標準化されたインターフェース（image.generate）

リクエスト

• prompt（文字列、必須）
• negative_prompt（文字列、任意）
• size（文字列、必須）、例：1024*1024、768*1024
• style（文字列、任意）
• seed（整数、任意）
• reference_image（文字列 | バイト列、任意）

レスポンス

• image_url（文字列）
• width（整数）
• height（整数）
• seed（整数）

クイックスタート（標準化されたリクエスト＋プレビュー）

最小限の標準化されたリクエスト本文：

{
  "prompt": "a cinematic portrait of a cyclist at dusk, soft rim light, shallow depth of field",
  "negative_prompt": "blurry, low quality, watermark",
  "size": "1024*1024",
  "seed": 1234
}

プレビューのワークフロー（ダウンロードしてから開く）：

curl -L -o output/aliyun-qwen-image/images/preview.png "<IMAGE_URL_FROM_RESPONSE>" && open output/aliyun-qwen-image/images/preview.png

ローカルヘルパースクリプト（JSON リクエスト → 画像ファイル）：

python skills/ai/image/aliyun-qwen-image/scripts/generate_image.py \\
  --request '{"prompt":"a studio product photo of headphones","size":"1024*1024"}' \\
  --output output/aliyun-qwen-image/images/headphones.png \\
  --print-response

パラメーターの概要

フィールド	必須	備考
prompt	はい	キーワードだけでなく、シーンを説明します。
negative_prompt	いいえ	可能な範囲で適用されますが、バックエンドで無視される場合があります。
size	はい	WxH 形式。例：1024*1024、768*1024。
style	いいえ	任意のスタイル指定です。
seed	いいえ	サポートされている場合、再現性の確保に使用します。
reference_image	いいえ	URL／ファイル／バイト列。SDK 固有のマッピングが必要です。

クイックスタート（Python＋DashScope SDK）

DashScope SDK を使用し、標準化されたリクエストを SDK 呼び出しにマッピングします。 注：qwen-image-max では、現在、DashScope SDK は ImageSynthesis ではなく、ImageGeneration（messages ベース）で正常に動作します。 使用している SDK バージョンで参照画像に別のフィールド名が必要な場合は、それに応じて input のマッピングを調整してください。

import os
from dashscope.aigc.image_generation import ImageGeneration

# Prefer env var for auth: export DASHSCOPE_API_KEY=...
# Or use ~/.alibabacloud/credentials with dashscope_api_key under [default].


def generate_image(req: dict) -> dict:
    messages = [
        {
            "role": "user",
            "content": [{"text": req["prompt"]}],
        }
    ]

    if req.get("reference_image"):
        # Some SDK versions accept {"image": <url|file|bytes>} in messages content.
        messages[0]["content"].insert(0, {"image": req["reference_image"]})

    response = ImageGeneration.call(
        model=req.get("model", "qwen-image-max"),
        messages=messages,
        size=req.get("size", "1024*1024"),
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # Pass through optional parameters if supported by the backend.
        negative_prompt=req.get("negative_prompt"),
        style=req.get("style"),
        seed=req.get("seed"),
    )

    # Response is a generation-style envelope; extract the first image URL.
    content = response.output["choices"][0]["message"]["content"]
    image_url = None
    for item in content:
        if isinstance(item, dict) and item.get("image"):
            image_url = item["image"]
            break
    return {
        "image_url": image_url,
        "width": response.usage.get("width"),
        "height": response.usage.get("height"),
        "seed": req.get("seed"),
    }

エラー処理

エラー	考えられる原因	対処方法
401/403	DASHSCOPE_API_KEY が未設定または無効	環境変数または ~/.alibabacloud/credentials と、アクセス権限の設定を確認します。
400	サポートされていないサイズまたは不正なリクエスト形式	一般的な WxH 形式を使用し、フィールドを検証します。
429	レート制限またはクォータ	バックオフを伴って再試行するか、同時実行数を減らします。
5xx	一時的なバックエンドエラー	バックオフを伴って 1〜2 回再試行します。

出力先

• デフォルトの出力先：output/aliyun-qwen-image/images/
• OUTPUT_DIR でベースディレクトリを上書きします。

運用ガイダンス

• 返された画像をオブジェクトストレージに保存し、メタデータには URL のみを永続化します。
• (prompt, negative_prompt, size, seed, reference_image hash) をキーに結果をキャッシュし、重複したコストを避けます。
• 一時的な 429／5xx レスポンスには、指数バックオフを伴う再試行を追加します。
• バックエンドによっては negative_prompt、style、seed が無視されるため、適用は可能な範囲にとどまるものとして扱います。
• レスポンスに画像 URL が含まれない場合は、明確なエラーを返し、簡略化したプロンプトでもう一度再試行します。

サイズに関する注意事項

• WxH 形式を使用します（例：1024*1024、768*1024）。
• 一般的なサイズを優先してください。サポートされていないサイズでは 400 エラーが返ることがあります。

アンチパターン

• モデル名やエイリアスを独自に作らず、公式のモデル ID のみを使用してください。
• 大きな Base64 データを DB の行に保存せず、オブジェクトストレージを使用してください。
• 生成に時間がかかる場合でも、ユーザーに進捗を表示してください。

ワークフロー

1. ユーザーの意図、リージョン、識別子、および操作が読み取り専用か変更を伴うものかを確認します。
2. 接続と権限を確認するため、最初に最小限の読み取り専用クエリを1つ実行します。
3. 明示的なパラメーターと限定された範囲を指定して、対象の操作を実行します。
4. 結果を検証し、出力／証拠ファイルを保存します。

参考資料

• DashScope SDK の対応関係とレスポンス解析のヒントについては、references/api_reference.md を参照してください。

• プロンプトのパターンと例については、references/prompt-guide.md を参照してください。

• 編集のワークフローには、skills/ai/image/aliyun-qwen-image-edit/ を使用してください。

• ソース一覧：references/sources.md