Category: provider

Model Studio Qwen Image#

Build consistent image generation behavior for the video-agent pipeline by standardizing image.generate inputs/outputs and using DashScope SDK (Python) with the exact model name.

Prerequisites#

• Install SDK (recommended in a venv to avoid PEP 668 limits):

bash

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

• Set DASHSCOPE_API_KEY in your environment, or add dashscope_api_key to ~/.alibabacloud/credentials (env takes precedence).

Critical model names#

Use one of these exact model strings:

• qwen-image-max
• qwen-image-plus-2026-01-09

Normalized interface (image.generate)#

Request#

• prompt (string, required)
• negative_prompt (string, optional)
• size (string, required) e.g. 1024*1024, 768*1024
• style (string, optional)
• seed (int, optional)
• reference_image (string | bytes, optional)

Response#

• image_url (string)
• width (int)
• height (int)
• seed (int)

Quickstart (normalized request + preview)#

Minimal normalized request body:

json

{
  "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
}

Preview workflow (download then open):

bash

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

Local helper script (JSON request -> image file):

bash

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/ai-image-qwen-image/images/headphones.png \\
  --print-response

Parameters at a glance#

FieldRequiredNotespromptyesDescribe a scene, not just keywords.negative_promptnoBest-effort, may be ignored by backend.sizeyesWxH format, e.g. 1024*1024, 768*1024.stylenoOptional stylistic hint.seednoUse for reproducibility when supported.reference_imagenoURL/file/bytes, SDK-specific mapping.

Quick start (Python + DashScope SDK)#

Use the DashScope SDK and map the normalized request into the SDK call. Note: For qwen-image-max, the DashScope SDK currently succeeds via ImageGeneration (messages-based) rather than ImageSynthesis. If the SDK version you are using expects a different field name for reference images, adapt the input mapping accordingly.

python

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"),
    }

Error handling#

ErrorLikely causeAction401/403Missing or invalid DASHSCOPE_API_KEYCheck env var or ~/.alibabacloud/credentials, and access policy.400Unsupported size or bad request shapeUse common WxH and validate fields.429Rate limit or quotaRetry with backoff, or reduce concurrency.5xxTransient backend errorsRetry with backoff once or twice.

Output location#

• Default output: output/ai-image-qwen-image/images/
• Override base dir with OUTPUT_DIR.

Operational guidance#

• Store the returned image in object storage and persist only the URL in metadata.
• Cache results by (prompt, negative_prompt, size, seed, reference_image hash) to avoid duplicate costs.
• Add retries for transient 429/5xx responses with exponential backoff.
• Some backends ignore negative_prompt, style, or seed; treat them as best-effort inputs.
• If the response contains no image URL, surface a clear error and retry once with a simplified prompt.

Size notes#

• Use WxH format (e.g. 1024*1024, 768*1024).
• Prefer common sizes; unsupported sizes can return 400.

Telegram / channel delivery#

When the user requests image generation via Telegram (or other channels), after generating and saving the image to workspace output/ai-image-qwen-image/images/, use the message tool to send the image: action=send, target=telegram, media=<file:// URL>. Always pass explicit target when the session may have mixed sources (e.g. control-ui): extract sender_id from Conversation info metadata in user messages and use target: "<sender_id>" (e.g. target: "6869266119") to ensure delivery to the correct Telegram DM and avoid "bot is not a member of the channel chat" errors. Use file:// absolute paths (e.g. file:///Users/fresh/.openclaw/workspace/output/ai-image-qwen-image/images/xxx.png). Do not use ~/ paths.

Anti-patterns#

• Do not invent model names or aliases; use official model IDs only.
• Do not store large base64 blobs in DB rows; use object storage.
• Do not omit user-visible progress for long generations.

References#

• See references/api_reference.md for a more detailed DashScope SDK mapping and response parsing tips.

• See references/prompt-guide.md for prompt patterns and examples.

• For edit workflows, use skills/ai/image/alicloud-ai-image-qwen-image-edit/.

• Source list: references/sources.md