alicloud-ai-image-qwen-image

Category: プロバイダー

Model Studio Qwen Image

検証

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

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

出力とエビデンス

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

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（int、任意）
• reference_image（文字列 | bytes、任意）

レスポンス

• image_url（文字列）
• width（int）
• height（int）
• seed（int）

クイックスタート（正規化されたリクエストとプレビュー）

最小限の正規化リクエスト本文：

{
  "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/alicloud-ai-image-qwen-image/images/preview.png "<IMAGE_URL_FROM_RESPONSE>" && open output/alicloud-ai-image-qwen-image/images/preview.png

ローカルヘルパースクリプト（JSON リクエストから画像ファイルを生成）：

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

パラメーター一覧

フィールド	必須	備考
prompt	はい	キーワードだけでなく、シーンを説明します。
negative_prompt	いいえ	可能な範囲で適用されますが、バックエンドで無視される場合があります。
size	はい	WxH 形式。例：1024*1024、768*1024。
style	いいえ	任意のスタイル指定です。
seed	いいえ	対応している場合は、再現性の確保に使用します。
reference_image	いいえ	URL／ファイル／bytes。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/alicloud-ai-image-qwen-image/images/
• OUTPUT_DIR でベースディレクトリを上書きできます。

運用上のガイダンス

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

サイズに関する注意

• 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/alicloud-ai-image-qwen-image-edit/ を使用してください。

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