Wan 2.1 text-to-image V2 API reference - Alibaba Cloud Model Studio

This topic describes the input and output parameters of the Wan Text-to-image V2 model.

Model overview

Performance showcase

You can experience the text-to-image effects on the Wan official website.

Note

The features on the Wan official website may differ from the capabilities supported by the API. For specific capabilities, refer to those listed in this API reference. This topic will be updated promptly when new features are added.

20250116143739

Model introduction

Version	Name	Description
Wan Text-to-image 2.1	wan2.1-t2i-turbo	Faster generation speed, general-purpose model.
Wan Text-to-image 2.1	wan2.1-t2i-plus	Richer details in generated images, slightly slower speed, general-purpose model.

Name	Unit price	Rate limits (shared between Alibaba Cloud account and RAM users)		Free quota
		Requests per second (RPS) for task submission	Number of concurrent tasks
wan2.1-t2i-turbo	$0.025/image	2	2	Free quota: 200 images each Validity period: 180 days after activation of Alibaba Cloud Model Studio
wan2.1-t2i-plus	$0.05/image	2	2

For more information, see Billing and rate limiting.

Prerequisites

The Text-to-image V2 API supports calls through HTTP and DashScope SDK.

Before you make a call, you must first obtain an API key and set the API key as an environment variable.

If you need to use SDK, you must install the SDK for Python or Java.

HTTP calls

Image model processing takes a long time. To avoid request timeouts, HTTP calls only support asynchronous retrieval of results. You need to make two requests:

Create task: Send a request to create a task, which will return a task ID.
Query results using the ID: Use the task ID to query the task status and the results. If successful, an image URL will be returned, which is valid for 24 hours.

Note

After you create a task, it will be added to a queue. Later, call the query interface to get the task status and results based on the task ID.

Text-to-image generation takes approximately 1-3 minutes. The specific time depends on the number of queued tasks and service execution conditions. Please be patient when retrieving results.

Step 1: Create task

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

Request parameters	Text-to-image Positive prompt Generate an image based on the prompt. `curl -X POST https://dashscope-intl.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": "wan2.1-t2i-turbo", "input": { "prompt": "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers" }, "parameters": { "size": "10241024", "n": 1 } }'` Positive + negative prompt Generate an image based on the prompt, avoiding "people" elements in the generated image. `curl -X POST https://dashscope-intl.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": "wan2.1-t2i-turbo", "input": { "prompt": "Snow, white chapel, aurora, winter scenario, soft light.", "negative_prompt": "people" }, "parameters": { "size": "10241024", "n": 1 } }'`
Headers
Content-Type `string` (Required) The type of the request content. This parameter must be set to `application/json`.
Authorization `string` (Required) The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a.
X-DashScope-Async `string` (Required) The asynchronous processing parameter. HTTP requests only support asynchronous mode, so this parameter must be set to `enable`.
Request body
model `string` (Required) The model name. Example: wan2.1-t2i-turbo.
input `object` (Required) Basic input information, such as prompts. Properties prompt `string` (Required) The positive prompt, used to describe the elements and visual characteristics that you expect in the generated image. Supports Chinese and English, with a maximum length of 800 characters. Each Chinese character or letter counts as one character. Content exceeding this limit will be truncated. Example: An orange cat sitting, with a joyful expression, lively and cute, realistic and accurate. For tips on using prompts, see Text-to-image prompt guide. negative_prompt `string` (Optional) The negative prompt, used to describe contents you do not want in the image. It places restrictions on the image. Supports Chinese and English, with a maximum length of 500 characters. Content exceeding this limit will be truncated. Example: Low resolution, errors, worst quality, low quality, defects, extra fingers, poor proportions.
parameters `object` (Optional) The image processing parameters. Properties size `string` (Optional) The resolution of the generated image. Default value: 10241024. The pixel range for image width and height is: [512, 1440], in pixels. These can be combined in any way to set different image resolutions, up to 2 million pixels. n `integer` (Optional) The number of images to generate. The value range is 1-4 images, with a default of 4. seed* `integer` (Optional) The random seed, used to control the randomness of model-generated content. The seed parameter value range is `[0, 2147483647]`. If not provided, the algorithm automatically generates a random seed. If provided, seeds are generated for `n` images. For example, if n=4, the algorithm will generate images using seed, seed+1, seed+2, and seed+3. If you want the generated content to remain relatively stable, you can use the same seed parameter value. prompt_extend `bool` (Optional) Specifies whether to enable intelligent prompt rewriting. When enabled, an LLM will intelligently rewrite the input prompt, only effective for positive prompts. This significantly improves generation results for shorter prompts but increases processing time by 3 to 4 seconds. true: Default value, enables intelligent rewriting. false: Disables intelligent rewriting. watermark `bool` (Optional) Whether to add a watermark. The watermark is in the lower right corner of the image with the text "AI Generated". false: Default value, no watermark is added. true: Add watermark.

Response parameters	Successful response `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` Error response `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx" }`
output `object` The task output information. Properties task_id `string` The task ID. task_status `string` The task status. Valid values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN
request_id `string` The request ID. It can be used for tracing and troubleshooting.
code `string` The error code for a failed request. This parameter is not returned when the request is successful.
message `string` The error message for a failed request. This parameter is not returned when the request is successful.

Step 2: Query results by task ID

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters	Query task results Replace `86ecf553-d340-4e21-xxxxxxxxx` with the actual task_id. `curl -X GET \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx`
Headers
Authorization `string` (Required) The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a.
Path parameters
task_id `string` (Required) The task ID.

Response parameters	Task succeeded Task data (such as task status and image URLs) is only retained for 24 hours and will be automatically deleted. Save the generated images promptly. { "request_id": "f767d108-7d50-908b-a6d9-xxxxxx", "output": { "task_id": "d492bffd-10b5-4169-b639-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-01-08 16:03:59.840", "scheduled_time": "2025-01-08 16:03:59.863", "end_time": "2025-01-08 16:04:10.660", "results": [ { "orig_prompt": "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers", "actual_prompt": "A flower shop with exquisite carved windows, beautiful dark wooden doors with brass handles. Inside, various fresh flowers are displayed, including roses, lilies, and sunflowers, vibrant and full of life. The background is a cozy indoor scene, with the street visible through the windows. High-definition realistic photography, medium shot composition.", "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png" } ], "task_metrics": { "TOTAL": 1, "SUCCEEDED": 1, "FAILED": 0 } }, "usage": { "image_count": 1 } } Task failed If the task fails for some reason, the task status will be set to FAILED, and the code and message fields will show the reason. `{ "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d", "output": { "task_id": "86ecf553-d340-4e21-af6e-xxxxxx", "task_status": "FAILED", "code": "InvalidParameter", "message": "xxxxxx", "task_metrics": { "TOTAL": 4, "SUCCEEDED": 0, "FAILED": 4 } } }` Task partially failed The model can generate multiple images in a single task. As long as one of the images is generated successfully, the task status will be marked as `SUCCEEDED`, and the corresponding image URL will be returned. For images that fail to generate, the result will include the corresponding failure reason. Only successful results will be counted in the usage statistics. `{ "request_id": "85eaba38-0185-99d7-8d16-xxxxxx", "output": { "task_id": "86ecf553-d340-4e21-af6e-xxxxxx", "task_status": "SUCCEEDED", "results": [ { "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png" }, { "code": "InternalError.Timeout", "message": "An internal timeout error has occured during execution, please try again later or contact service support." } ], "task_metrics": { "TOTAL": 2, "SUCCEEDED": 1, "FAILED": 1 } }, "usage": { "image_count": 1 } }`
output `object` The task output information. Properties task_id `string` The task ID. task_status `string` The task status. Valid values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN submit_time `string` The time when the task was submitted. scheduled_time `string` The execution duration of the task. end_time `string` The time when the task was completed. results `array object` The task result list, including image URL, prompt, and error message in case of partial failure. Data structure `{ "results": [ { "orig_prompt": "", "actual_prompt": "", "url": "" }, { "code": "", "message": "" } ] }` Properties orig_prompt `string` The original input prompt. actual_prompt `string` The actual prompt used after intelligent prompt rewriting. This field is not returned when prompt rewriting is not enabled. url `string` The URL of the generated image. code `string` The image error code. This field is returned when part of the task fails. message `string` The image error message. This field is returned when part of the task fails. task_metrics `object` The task result statistics. Properties TOTAL `integer` The total number of tasks. SUCCEEDED `integer` The number of successful tasks. FAILED `integer` The number of failed tasks. code `string` The error code for a failed request. This parameter is not returned when the request is successful. message `string` The error message for a failed request. This parameter is not returned when the request is successful.
usage `object` The output statistics. Only counts successful results. Properties image_count `integer` The number of images generated by the model.
request_id `string` The request ID. It can be used for tracing and troubleshooting.

DashScope SDK

Make sure you have installed the latest version of the DashScope SDK to avoid errors: Install SDK.

DashScope SDK currently supports Python and Java.

The parameter names in the SDK are basically the same as the HTTP interface. The parameter structure depends on the SDK encapsulation of different languages. For parameter descriptions, refer to HTTP calls.

Because image model processing takes a long time, the underlying service uses an asynchronous approach. The SDK provides encapsulation at the upper layer and supports both synchronous and asynchronous calling methods.

Text-to-image generation takes approximately 1-3 minutes. The specific time depends on the number of queued tasks and service execution conditions. Please be patient when retrieving results.

Python SDK

Synchronous

Sample request

Text-to-image

from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
prompt = "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers"

print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=os.getenv("DASHSCOPE_API_KEY"),
                          model="wan2.1-t2i-turbo",
                          prompt=prompt,
                          n=1,
                          size='1024*1024')
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
    # Save images in the current directory
    for result in rsp.output.results:
        file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
        with open('./%s' % file_name, 'wb+') as f:
            f.write(requests.get(result.url).content)
else:
    print('sync_call Failed, status_code: %s, code: %s, message: %s' %
          (rsp.status_code, rsp.code, rsp.message))

Sample response

The URL is valid for 24 hours. Download the image in time.

{
    "status_code": 200,
    "request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [{
            "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
            "orig_prompt": "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers",
            "actual_prompt": "An exquisite flower shop with elegant carved windows and beautiful wooden doors with brass handles. Inside, various colorful flowers are displayed, such as roses, tulips, and lilies. The background is a cozy indoor scene with soft lighting, creating a peaceful and comfortable atmosphere. High-definition realistic photography, close-up centered composition."
        }],
        "submit_time": "2025-01-08 19:36:01.521",
        "scheduled_time": "2025-01-08 19:36:01.542",
        "end_time": "2025-01-08 19:36:13.270",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Asynchronous

Sample request

Text-to-image

from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
prompt = "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers"


def async_call():
    print('----create task----')
    task_info = create_async_task()
    print('----wait task done then save image----')
    wait_async_task(task_info)


# Create an asynchronous task
def create_async_task():
    rsp = ImageSynthesis.async_call(api_key=os.getenv("DASHSCOPE_API_KEY"),
                                    model="wan2.1-t2i-turbo",
                                    prompt=prompt,
                                    n=1,
                                    size='1024*1024')
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))
    return rsp


# Wait for the asynchronous task to complete
def wait_async_task(task):
    rsp = ImageSynthesis.wait(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
        for result in rsp.output.results:
            file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
            with open('./%s' % file_name, 'wb+') as f:
                f.write(requests.get(result.url).content)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


# Get asynchronous task information
def fetch_task_status(task):
    status = ImageSynthesis.fetch(task)
    print(status)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))


# Cancel the task. Only tasks in the PENDING state can be canceled
def cancel_task(task):
    rsp = ImageSynthesis.cancel(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    async_call()

Sample response

1. Create a task

{
	"status_code": 200,
	"request_id": "31b04171-011c-96bd-ac00-f0383b669cc7",
	"code": "",
	"message": "",
	"output": {
		"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
		"task_status": "PENDING",
		"results": []
	},
	"usage": null
}

2. Query task results

The URL is valid for 24 hours. Download the image in time.

{
    "status_code": 200,
    "request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [{
            "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
            "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display.",
            "actual_prompt": "An exquisite flower shop with windows decorated with elegant carvings and a beautiful wooden door with a brass handle. Inside, a variety of brightly colored flowers, such as roses, tulips, and lilies, are on display. The background is a warm indoor scene with soft lighting, creating a peaceful and comfortable atmosphere. High-definition, photorealistic photography, close-up, centered composition."
        }],
        "submit_time": "2025-01-08 19:36:01.521",
        "scheduled_time": "2025-01-08 19:36:01.542",
        "end_time": "2025-01-08 19:36:13.270",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Java SDK

Synchronous

Sample request

Text-to-image

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {

  static {
     Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
  }
  
  public static void basicCall() throws ApiException, NoApiKeyException {
        String prompt = "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers";
        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .model("wan2.1-t2i-turbo")
                        .prompt(prompt)
                        .n(1)
                        .size("1024*1024")
                        .build();

        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---sync call, please wait a moment----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

  public static void listTask() throws ApiException, NoApiKeyException {
    ImageSynthesis is = new ImageSynthesis();
    AsyncTaskListParam param = AsyncTaskListParam.builder().build();
    ImageSynthesisListResult result = is.list(param);
    System.out.println(result);
  }

  public void fetchTask() throws ApiException, NoApiKeyException {
    String taskId = "your task id";
    ImageSynthesis is = new ImageSynthesis();
    // If set DASHSCOPE_API_KEY environment variable, apiKey can null.
    ImageSynthesisResult result = is.fetch(taskId, null);
    System.out.println(result.getOutput());
    System.out.println(result.getUsage());
  }

  public static void main(String[] args){
    try{
      basicCall();
      //listTask();
    }catch(ApiException|NoApiKeyException e){
      System.out.println(e.getMessage());
    }
  }
}

Sample response

The URL is valid for 24 hours. Download the image in time.

{
    "request_id": "22f9c744-206c-9a78-899a-xxxxxx",
    "output": {
        "task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [{
           "orig_prompt": "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers",
            "actual_prompt": "A flower shop with exquisite carved windows, beautiful dark wooden doors slightly ajar. Inside, various fresh flowers are displayed, including roses, lilies, and sunflowers, vibrant and fragrant. The background is a cozy indoor scene with soft lighting filtering through the windows onto the flowers. High-definition realistic photography, medium shot composition.",
            "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
        }],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Asynchronous

Sample request

Text-to-image

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {
    static {
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    }
    
    public void asyncCall() {
        System.out.println("---create task----");
        String taskId = this.createAsyncTask();
        System.out.println("---wait task done then return image url----");
        this.waitAsyncTask(taskId);
    }


    /**
     * Create an asynchronous task
     * @return taskId
     */
    public String createAsyncTask() {
        String prompt = "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers";
        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .model("wan2.1-t2i-turbo")
                        .prompt(prompt)
                        .n(1)
                        .size("1024*1024")
                        .build();

        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            result = imageSynthesis.asyncCall(param);
        } catch (Exception e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        String taskId = result.getOutput().getTaskId();
        System.out.println("taskId=" + taskId);
        return taskId;
    }


    /**
     * Wait for the asynchronous task to complete
     * @param taskId Task ID
     * */
    public void waitAsyncTask(String taskId) {
        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            //If DASHSCOPE_API_KEY is already set in environment variables, the apiKey parameter in the wait() method can be set to null
            result = imageSynthesis.wait(taskId, null);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        System.out.println(JsonUtils.toJson(result.getOutput()));
    }


    public static void main(String[] args){
        Main main = new Main();
        main.asyncCall();
    }
}

Sample response

1. Create a task

{
	"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}

2. Query task results

{
    "request_id": "22f9c744-206c-9a78-899a-xxxxxx",
    "output": {
        "task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [{
           "orig_prompt": "A flower shop with exquisite windows, beautiful wooden doors, displaying flowers",
            "actual_prompt": "A flower shop with exquisite carved windows, beautiful dark wooden doors slightly ajar. Inside, various fresh flowers are displayed, including roses, lilies, and sunflowers, vibrant and fragrant. The background is a cozy indoor scene with soft lighting filtering through the windows onto the flowers. High-definition realistic photography, medium shot composition.",
            "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
        }],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Error codes

If the model call fails and returns an error message, see Error messages for solutions.

Specific status codes for this API:

HTTP status code	API Error Code (code)	Description
400	IPInfringementSuspect	The input data may involve intellectual property infringement. Check your input to ensure it does not contain such content.

FAQ

Billing and rate limiting

Free quota

Overview: Free quota refers to the number of output images successfully generated by the model. Input images and failed model processing do not consume the free quota.
How to get: You automatically get it after activating Model Studio, valid for 180 days.
Account usage: Alibaba Cloud account and its RAM users share the free quota.
For more information, see Free quota for new users.

Limited-time free

When a model is marked as limited-time free trial, the model is in public preview. After the free quota is exhausted, the model cannot be used.

Billing description

When a model has a specific unit price, such as $0.2/second, the model has been commercialized. You need to pay for it after its free quota is exhausted or expired.
Billing item: Only successfully generated output images are charged. Other cases are not charged.
Payment method: All payments are made by the Alibaba Cloud account. RAM users cannot pay independently. To check your bills, go to Billing Overview.
Recharge channel: You can recharge on the Alibaba Cloud Management Console Billing and Cost page.
Model usage statistics: You can check model usage and call count by visiting Alibaba Cloud Model Studio's Model Monitoring page.
For more information, see Billing items.

Rate limit

Overview: Alibaba Cloud account and its RAM users share the limits.

Configure domain whitelist to access image OSS links

Generated images are stored in OSS, and each image is assigned an OSS link, such as https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png. OSS links allow public access. You can use this link to view or download the image. The link is valid for only 24 hours.

If your business has high security requirements and cannot access OSS links, you need to configure a separate whitelist for external network access Add the following domains to your whitelist to access image links.

# OSS domain list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

Model overview

Prerequisites

HTTP calls

Step 1: Create task

Request parameters

Text-to-image

Positive prompt

Positive + negative prompt

Headers

Request body

Response parameters

Successful response

Error response

Step 2: Query results by task ID

Request parameters

Query task results

Headers

Path parameters

Response parameters

Task succeeded

Task failed

Task partially failed

DashScope SDK

Python SDK

Synchronous

Sample request

Text-to-image

Sample response

Asynchronous

Sample request

Text-to-image

Sample response

Java SDK

Synchronous

Sample request

Text-to-image

Sample response

Asynchronous

Sample request

Text-to-image

Sample response

Error codes

FAQ

Billing and rate limiting

Configure domain whitelist to access image OSS links