Image API documentation FAQ - Alibaba Cloud Model Studio

This topic answers frequently asked questions about image APIs, including debugging, billing, rate limiting, and common API errors.

The image models covered in this topic include Wan text-to-image V2, person instance segmentation, and image erase completion.

Debug APIs locally

Image APIs support HTTP calls. The following section uses the Wan text-to-image API as an example to show how to debug an HTTP API call locally.

Activate the model service and obtain an API key. Then, set the API key as an environment variable.
Find the curl command in the image API documentation.

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
    }
}'

If you use macOS or Linux, execute the curl command in the terminal.
If you use Windows, use an API platform such as Postman or Apifox to send HTTP requests.

Note: When you use an API platform to send a request, you must replace $DASHSCOPE_API_KEY in the curl command Bearer $DASHSCOPE_API_KEY with your actual API key, for example, Bearer sk-xxxxxx.

Billing and rate limiting

Billing example

Note: Image Model 1 and Image Model 2 in the table are examples only and are not real model names.

Model	Free quota (View)	Unit price	Rate limit (shared by Alibaba Cloud account and RAM users)
Model	Free quota (View)	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

Description: The free quota is based on the number of images that are successfully generated by the model. Input images or failed model processing will not consume the quota.
How to get: The free quota is automatically granted after you activate the Alibaba Cloud Model Studio service and is valid for 90 days.
Usage: An Alibaba Cloud account and its RAM users share the free quota.
For more information, see Free quota for new users.

Free for a limited time

If the billing method is "Free for a limited time", the model is in public preview. You cannot use the model after the free quota is exhausted.

Billing description

If a specific unit price is provided, such as $0.02/image, the model is commercialized. You are charged for using the model after your free quota is exhausted or expires.
Billable item: You are charged only for successfully generated output images. No fees are charged in other cases.
Billing method: Fees are charged to your Alibaba Cloud account. RAM users cannot be independently metered or billed. All usage is charged to the Alibaba Cloud account that owns the RAM users. To view your billing information, go to the Billing Overview page in the Alibaba Cloud Management Console.
Top-up method: You can add funds to your account on the Expenses and Costs page in the Alibaba Cloud Management Console.
Model call statistics: To view the model call volume and count, go to the Model Observation (Singapore or Beijing) page on the Alibaba Cloud Model Studio platform.
For more information about billing, see Billable items.

Rate limiting

Description: An Alibaba Cloud account and its RAM users share the rate limits.

API errors

Image download failed

Scenario: When you use your own image URL (not the example URL from the documentation) to request an API, the error message "Reference image download failed, please check image url." is returned.

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

Possible cause: The input image URL is incorrect, inaccessible, or has restricted download permissions. This prevents the model service from successfully downloading the image.

Solution: Ensure that the image URL is complete and allows public network access. You can upload the image to a self-managed storage service that is publicly accessible or to a cloud storage service such as OSS. Make sure that the image URL allows public network access.

The curl command for the task creation API fails

Scenario: You copy the curl command for a task creation API from the documentation and an error occurs when you execute it. The following curl command for the image background generation model is used as an example.

Example: curl command for the task creation API of 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"
    }
}'

The error message "Required body invalid, please check the request body format." is returned.

{
    "request_id": "d306ae65-3f6d-9d6c-acfb-xxxxxx",
    "code": "InvalidParameter",
    "message": "Required body invalid, please check the request body format."
}

Possible cause: The request body of the task creation API contains Chinese characters. If the client that executes the curl command does not support parsing Chinese characters, the request body may not be parsed correctly, which causes the error.

Solution: If you use macOS or Linux, execute the curl command directly in the terminal. If you use Windows, use an HTTP API platform such as Postman or Apifox to send the request.

Resource download timeout when calling APIs from outside China

Scenario: When you call an API from outside China and the image resources are stored in a region outside the Chinese mainland, a resource download timeout error is likely to occur. The error message is as follows:

Download the media resource timed out during the data inspection process

Primary cause: Network instability between regions outside the Chinese mainland and the service endpoint can cause a timeout when the service attempts to download images.

Solution: Store the image resources in a region within the Chinese mainland and configure acceleration. Note that you cannot configure the image download timeout period for an Alibaba Cloud account.

Alibaba Cloud Model Studio:FAQ