Skip to main content
Qwen Cloud home page
Docs
Models & inference

Images & videos FAQ

Common questions about image and video generation — billing, API errors, model differences, input requirements, and output URLs.

Debugging

How do I debug image API calls locally?

Image APIs support standard HTTP calls. To test locally:
  1. Activate the model service and get an API key. Then set the API key as an environment variable.
  2. Find the curl command in the image API docs and run it in a terminal (macOS/Linux) or use an API platform like Postman or Apifox (Windows).
When using an API platform, replace $DASHSCOPE_API_KEY in the Authorization header with your actual API key, for example, Bearer sk-xxxxxx.

Billing and rate limits

How does billing work for image models?

Each image model has a free quota and may have a per-image price. Free quota and rate limits are shared across a Qwen Cloud account. Only successfully generated output images are billed — input images and failed requests do not consume quota or incur charges. For full billing details, see Billing Overview.

What does "free for a limited time" mean?

The model is in public preview. Once the free quota is exhausted, the model becomes unavailable.

How do I get the free quota?

The free quota is granted automatically when you activate Qwen Cloud. It is valid for 90 days and shared across your Qwen Cloud account. See Free quota for new users.

When do paid charges start?

If a model lists a specific unit price, charges begin once the free quota is exhausted or expires. Fees are billed to the Qwen Cloud account.

How does billing work for video models?

Video generation is billed by the duration of successfully generated video. Failed tasks are not charged. The free quota is shared across image and video generation models.

API errors

Common image API errors:
Error codeMessageTypical cause
BadRequest.InputDownloadFailedReference image download failedImage URL is incorrect, unreachable, or access-restricted
InvalidParameterRequired body invalidRequest body contains Chinese characters that the client cannot parse
(Download timeout)Download the media resource timed outNetwork instability between regions outside the Chinese mainland and the service endpoint

BadRequest.InputDownloadFailed: "Reference image download failed"

{
  "request_id": "657f0d1b-76d0-9e3e-b6d6-xxxxxx",
  "output": {
    "task_id": "5e6fa974-9a25-4271-8659-xxxxxx",
    "task_status": "FAILED",
    "code": "BadRequest.InputDownloadFailed",
    "message": "Reference image download failed, please check image url."
  }
}
Cause: The image URL is incorrect, unreachable, or access-restricted. The service downloads the image during processing — if the download fails, the task fails. Solution: Ensure the URL is complete and publicly accessible. If the image requires authentication, upload it to public storage (like OSS) and use the new URL.

InvalidParameter: "Required body invalid"

{
  "request_id": "d306ae65-3f6d-9d6c-acfb-xxxxxx",
  "code": "InvalidParameter",
  "message": "Required body invalid, please check the request body format."
}
Cause: The curl request body contains Chinese characters that the client cannot parse correctly. Solution: Run the curl command in a terminal (macOS/Linux handle UTF-8 natively), or use an HTTP platform like Postman or Apifox.

Resource download timeout from outside the Chinese mainland

Download the media resource timed out during the data inspection process
Cause: Network instability between the image storage region (outside the Chinese mainland) and the service endpoint causes download timeouts. Solution: Store images in a region with stable connectivity to the service endpoint and configure acceleration. The download timeout period is not configurable.

Wan2.6 image generation and editing

APIs: Synchronous, Create task, Query result

What image editing modes does Wan2.6 support?

Wan2.6 supports two modes controlled by the enable_interleave parameter:
  • Image editing (enable_interleave=false, default): Edits images, applies style transfer, or generates subject-consistent images. Input: 1–4 images. Output: 1–4 images.
  • Interleaved text-image output (enable_interleave=true): Generates mixed text-image content. Input: 0–1 images. Streaming is required.

What are the image input requirements?

  • Formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP.
  • Resolution: Width and height each between 240 and 8,000 pixels.
  • File size: Maximum 10 MB per image.
  • Image count: Editing mode: 1–4 images. Interleaved mode: 0–1 image.

How do I pass images using Base64 encoding?

Instead of a public URL, pass a Base64-encoded string in the format data:{mime_type};base64,{base64_data} (for example, data:image/jpeg;base64,/9j/4AAQ...).

How do I use the interleaved text-image output mode?

Interleaved text-image output (enable_interleave=true) requires streaming. Set both:
  1. X-DashScope-Sse header to enable
  2. parameters.stream to true
Use max_images (1–5, default 5) to control the maximum number of generated images. The parameter n must remain 1 in this mode.

What output resolutions are supported?

Image editing mode: Use 1K (default, 1280*1280) or 2K (2048*2048) to match input proportions, or specify exact width*height within [768*768, 2048*2048]. Interleaved mode: Dimensions within [768*768, 1280*1280]. Recommended: 1280*1280, 800*1200, 1200*800, 960*1280, 1280*960, 720*1280, 1280*720, 1344*576.

How long are generated image URLs valid?

Generated image URLs are valid for 24 hours. Download images promptly after generation.

Qwen text-to-image

API: Qwen text-to-image

Should I enable or disable the prompt_extend parameter?

Enable (default) for simple prompts to improve quality. Disable (false) for precise control, detailed descriptions, or low latency. See Image prompt guide.

What are the differences between the Qwen-Image models?

Unified image generation and editing models (recommended):
  • qwen-image-2.0-pro: Professional text rendering, fine-grained realism, stronger semantic adherence. Synchronous only.
  • qwen-image-2.0: High-quality generation, faster than qwen-image-2.0-pro. Synchronous only.
Text-to-image models:
  • qwen-image-max: Enhanced realism with better textures and details than qwen-image-plus.
  • qwen-image-plus / qwen-image: Identical capabilities. qwen-image-plus is the current recommended option; qwen-image is retained for backward compatibility.

Qwen image editing

API: Qwen image editing

What languages do the Qwen image editing models support?

The models officially support Simplified Chinese and English. Other languages may work but results are not guaranteed.

What are the image input requirements for Qwen image editing?

  • Formats: JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF (first frame only). Output is always PNG.
  • Resolution: Width and height between 384 and 3072 pixels. Images outside this range may produce blurred output or increase processing time.
  • File size: Maximum 10 MB per image.
  • Number of images: 1 to 3 images per request.

How do I pass images using Base64 encoding?

Pass a Base64-encoded image string instead of a URL in the format data:{mime_type};base64,{base64_data} (such as data:image/jpeg;base64,/9j/4AAQ...). See code samples in the API reference for complete examples.

Z-Image

How do I view model invocation metrics?

Metrics (invocation count, success rate) are available one hour after the generation task completes on the Monitoring page. See also: Bill query and cost management.

Video generation

APIs: Text-to-video, Image-to-video, Image-to-video (first & last frames), Video editing

What are the image input requirements for image-to-video?

  • Formats: Common formats such as JPEG, JPG, PNG, WEBP.
  • Size: Maximum 10 MB per image.
  • URL: Must be a publicly accessible HTTP(S) URL. The service downloads the image at generation time.
Requirements differ between wan2.6 and wan2.5 — see the API reference for the model you are using.

How long does video generation take?

Video generation is asynchronous. After submitting a task, poll the query endpoint every 10–30 seconds until the status transitions from PENDING or RUNNING to SUCCEEDED or FAILED. Generation time depends on video duration, resolution, and queue load — plan for one to several minutes.

How long are generated video URLs valid?

Generated video URLs are valid for 24 hours. Download the video promptly after the task succeeds.