FAQ - Alibaba Cloud Model Studio

Debugging

How do I debug image API calls locally?

Image APIs use standard HTTP. This example uses the Wan text-to-image API with curl.

Activate the model service and get an API key, then set it as an environment variable.
Find the curl command in the API documentation. For example:

Example: curl command for text-to-image

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

On macOS or Linux, run the command directly in a terminal.
On Windows, use an API platform such as Postman or Apifox to send the HTTP request.

Note: 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:

Model	Free quota	Unit price	QPS limit for task submission	Number of concurrent tasks
Image Model 1	500 images	Free for a limited time	2	1
Image Model 2	500 images	$0.02/image	2	1

Free quota and rate limits are shared across the Alibaba Cloud account and all RAM users.

What does "free for a limited time" mean?

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

What counts as a billable image?

Only successfully generated images are billed. Input images and failed requests do not consume quota or incur charges.

How do I get the free quota?

Free quota is granted automatically when you activate Model Studio. It is valid for 90 days and shared across the account and all RAM users. For details, see Free quota for new users.

When do paid charges start?

Models with a specific unit price (for example, $0.02/image) are commercialized. Charges begin after the free quota is exhausted or expires. Fees are billed to the Alibaba Cloud account -- all usage rolls up to the parent account.

View bills: Go to the Billing Overview page in the Alibaba Cloud Management Console.
Add funds: Go to the Expenses and Costs page.
Monitor usage: Check the Monitoring page on the Model Studio platform (Singapore | Beijing).

For full billing details, see Billable items.

API errors

Common image API errors and solutions:

Error code	Message	Typical cause
`BadRequest.InputDownloadFailed`	Reference image download failed	Image URL is incorrect, unreachable, or access-restricted
`InvalidParameter`	url error, please check url	The `model` parameter is set to a text generation model name instead of an image generation model name
`InvalidParameter`	Required body invalid	Request body contains Chinese characters that the client cannot parse
(Timeout)	Download the media resource timed out	Network 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 from the URL during processing. Solution: Verify the URL is complete and publicly accessible. If the image requires authentication, upload it to a public storage service such as OSS and use the new URL.

`InvalidParameter`: "url error"

{
    "code": "InvalidParameter",
    "message": "url error, please check url！"
}

Cause: The model parameter does not match the endpoint being called. The image synthesis endpoint (/api/v1/services/aigc/text2image/image-synthesis) accepts only image generation model names. A text generation model name such as qwen-turbo is rejected with url error, even when the request URL is correct. In OpenAI-compatible mode, a text generation model name returns an empty response instead. Solution: Set model to an image generation model name such as wanx2.1-t2i-turbo and call the endpoint asynchronously.

Example: curl command for image generation

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "a cute cat"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

Image generation is asynchronous. The create-task call returns a task_id. Poll GET /api/v1/tasks/{task_id} until task_status becomes SUCCEEDED to get the URL of the generated image.

`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. Solution: On macOS or Linux, run curl directly in a terminal (handles UTF-8 natively). On Windows, use an API platform like Postman or Apifox.

Example: curl command for image background generation

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-background-generation-v2",
    "input": {
        "base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
        "ref_image_url": "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg",
        "ref_prompt": "mountains and sunset clouds",
        "reference_edge": {
            "foreground_edge": [
                "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png",
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/2c36cc4b7da027279e87311dac48fc2d5d784b1e72c0e-x4f1wC_fw658webp.png"
            ],
            "background_edge": [
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/0718a9741e07c52ca5506e75c4f2b99e22fff68a4c7d3-P9WGLr_fw658webp.png"
            ],
            "foreground_edge_prompt": [
                "pink peach blossoms",
                "cute puppy"
            ],
            "background_edge_prompt": [
                "leaves"
            ]
        }
    },
    "parameters": {
        "n": 4,
        "ref_prompt_weight": 0.5,
        "model_version": "v3"
    }
}'

Resource download timeout from outside the Chinese mainland

Download the media resource timed out during the data inspection process

Cause: Network instability between regions outside the Chinese mainland and the DashScope service endpoint causes download timeouts. Solution: Store image resources within the Chinese mainland and configure acceleration. The timeout period is not configurable.

​Debugging

​How do I debug image API calls locally?

​Billing and rate limits

​How does billing work for image models?

​What does "free for a limited time" mean?

​What counts as a billable image?

​How do I get the free quota?

​When do paid charges start?

​API errors

​BadRequest.InputDownloadFailed: "Reference image download failed"

​InvalidParameter: "url error"

​InvalidParameter: "Required body invalid"

​Resource download timeout from outside the Chinese mainland