intent

Generate images using Alibaba's Qwen image generation models (qwen-image-max or qwen-image-plus-2026-01-09) via the DashScope SDK. use this skill when you need to standardize image.generate inputs/outputs across the video-agent pipeline, map normalized request fields (prompt, negative_prompt, size, seed, reference_image) to SDK calls, handle error cases like rate limits and auth failures, or integrate image generation into downstream workflows (storage, caching, channel delivery).

inputs

Environment & credentials

• DASHSCOPE_API_KEY (env var, required): Alibaba DashScope API key. precedence: env var over ~/.alibabacloud/credentials file under [default] section with key dashscope_api_key.
• Python 3.7+ with dashscope package installed (pip install dashscope). recommended: use venv to avoid PEP 668 limits.

DashScope SDK

• dashscope.aigc.image_generation.ImageGeneration class for messages-based image generation.

Normalized request object

• prompt (string, required): scene description, not just keywords. example: "a cinematic portrait of a cyclist at dusk, soft rim light, shallow depth of field".
• negative_prompt (string, optional): quality/style hints to avoid. note: backend may ignore.
• size (string, required): WxH format. accepted: 1024*1024, 768*1024, 512*512. unsupported sizes return 400.
• style (string, optional): stylistic hint passed to backend. treat as best-effort.
• seed (int, optional): for reproducibility. backend may ignore.
• reference_image (string or bytes, optional): URL, file path, or bytes. SDK-specific mapping in messages content.
• model (string, optional, defaults to qwen-image-max): one of qwen-image-max or qwen-image-plus-2026-01-09.

External context (for channel delivery)

• sender_id (string, optional): Telegram user/chat ID extracted from conversation metadata. required only if sending result to Telegram.

procedure

1. validate credentials

   • input: DASHSCOPE_API_KEY env var or ~/.alibabacloud/credentials file.
   • check api key is set and non-empty.
   • output: boolean (credentials valid or missing). if missing, skip to decision point (fallback or error).

2. normalize request object

   • input: raw request dict with prompt, negative_prompt, size, seed, reference_image, model (optional).
   • validate prompt is non-empty string.
   • validate size matches WxH pattern (e.g., 1024*1024). reject if not.
   • set defaults: model = req.get("model", "qwen-image-max"), size = req.get("size", "1024*1024").
   • output: normalized request dict with all required fields present.

3. build messages array for SDK

   • input: normalized request object.
   • create initial messages structure: [{"role": "user", "content": [{"text": req["prompt"]}]}].
   • if reference_image is provided: insert {"image": req["reference_image"]} at position 0 in content array (before text).
   • output: messages array ready for SDK call.

4. call ImageGeneration.call()

   • input: messages array, model name, size, api_key, optional fields (negative_prompt, style, seed).
   • call ImageGeneration.call(model=..., messages=..., size=..., api_key=..., negative_prompt=..., style=..., seed=...).
   • capture response object or exception.
   • output: raw response object (on success) or exception object (on failure).

5. parse response envelope

   • input: response object from step 4.
   • extract: response.output["choices"][0]["message"]["content"] (list of content items).
   • iterate content list and find first item where isinstance(item, dict) and item.get("image") is truthy.
   • extract image_url, width, height from usage/metadata if available.
   • output: dict with image_url (string), width (int or null), height (int or null), seed (int from request or null).

6. save image file (optional)

   • input: image_url, output_dir (default output/ai-image-qwen-image/images/), filename (e.g., generated.png).
   • create output_dir if missing.
   • download image from url using curl or requests library.
   • save to {output_dir}/{filename}.
   • output: file path on disk (absolute path, no ~/).

7. cache result (optional)

   • input: normalized request (prompt, negative_prompt, size, seed, reference_image), image_url, response metadata.
   • hash cache key from (prompt, negative_prompt, size, seed, reference_image hash).
   • store (cache_key -> image_url, metadata) in local db or object storage.
   • output: cache entry written.

8. deliver via channel (optional, if Telegram or other)

   • input: image file path (absolute, e.g., file:///Users/.../output/ai-image-qwen-ai-image/images/xxx.png), sender_id (from conversation metadata), target channel (e.g., "telegram").
   • call message tool: action=send, target=<sender_id>, media=<file_url>.
   • note: always pass explicit target if session may have mixed sources; do not use ~/ paths.
   • output: delivery receipt or error.

decision points

if api_key is missing or invalid

• behavior: raise clear error message naming env var DASHSCOPE_API_KEY and fallback path ~/.alibabacloud/credentials.
• do not attempt SDK call.

if size format is invalid (not WxH)

• behavior: reject with 400-like error. suggest common sizes: 1024*1024, 768*1024, 512*512.
• do not call SDK.

if response status code is 401/403

• behavior: invalid or expired api key.
• action: check env var, credentials file, and Alibaba access policy. surface error to user.

if response status code is 400

• behavior: unsupported size, malformed request, or backend validation failure.
• action: validate request shape, retry with common size, or simplify prompt and retry once.

if response status code is 429 (rate limit) or 5xx (transient backend error)

• behavior: transient failure.
• action: retry with exponential backoff (e.g., 1s, 2s, 4s). max 2-3 retries. if still fails, surface error.

if response contains no image_url

• behavior: unexpected response shape.
• action: log full response, simplify prompt, retry once. if retry also fails, error and ask user to check prompt quality.

if reference_image is provided

• behavior: insert image into messages content array before text.
• note: exact field name and format may vary by SDK version; adapt mapping if needed.

if negative_prompt, style, or seed are not in response

• behavior: backend may ignore these inputs.
• action: treat as best-effort. log a warning if user requested but backend did not honor.

if user requests delivery via Telegram (or other channel)

• behavior: after saving image file, call message tool with explicit target=<sender_id>.
• decision: extract sender_id from conversation metadata. if not found, error and ask user for chat id.
• do not use ~/ paths; use absolute file:/// paths.

if cache hit (same prompt/negative_prompt/size/seed/reference_image hash)

• behavior: return cached image_url and metadata instead of calling SDK.
• action: skip SDK call, avoid duplicate cost, reduce latency.

output contract

on success (step 5 complete)

• data format: dict with keys:
  • image_url (string): valid HTTPS url to generated image. example: https://dashscope-result-xxx.oss-cn-hangzhou.aliyuncs.com/....
  • width (int or null): pixel width if available.
  • height (int or null): pixel height if available.
  • seed (int or null): seed value used (from request or backend).
• file location (optional): {OUTPUT_DIR}/ai-image-qwen-ai-image/images/{filename}.png where OUTPUT_DIR defaults to output/ in workspace. use absolute paths, no ~/.

on error

• format: exception or error dict with keys:
  • error_code (string): 401, 403, 400, 429, 5xx, or custom code.
  • message (string): human-readable description.
  • retry_after (int, optional): seconds to wait before retry (present for 429).

cache storage (optional)

• format: key-value store or db row with:
  • cache_key (string): hash of (prompt, negative_prompt, size, seed, reference_image).
  • image_url (string): result url.
  • metadata (dict): width, height, seed, timestamp.
  • ttl: recommend 30-90 days.

outcome signal

• user sees image_url in response: skill worked. user can open url or download to disk.
• image file saved to workspace: user can verify file exists at output/ai-image-qwen-ai-image/images/{filename}.png and open in viewer.
• image delivered to Telegram: user receives image in Telegram DM with no "bot not member of channel" errors.
• latency improvement on cache hit: user observes <1s response on repeated (prompt, negative_prompt, size, seed) tuple.
• clear error message on failure: user sees specific error code (401, 400, 429, 5xx) and actionable remediation (check api key, simplify prompt, retry later, etc.).