The Wanx text-to-image model generates images from text prompts, supporting a variety of artistic styles and photorealistic photography effects to meet diverse creative needs.
Quick entry:Try it online (Singapore | Virginia | Beijing) | Wanx official website
NoteThe features of the Wanx official website may differ from the capabilities supported by the API. This document is based on the actual capabilities of the API and will be kept in sync as features are updated.
Prerequisites
Before making calls, first obtain and configure an API Key, and then configure the API Key as an environment variable. To make calls through the SDK, please install the DashScope SDK.
ImportantThe Singapore, United States (Virginia), and China (Beijing) regions have their own dedicated API Key and request address, which cannot be mixed. Cross-region calls will cause authentication failures or service errors. For more information, see Regions, service deployment scope, and endpoints.
ImportantAlibaba Cloud Model Studio has launched workspace-specific domain names for the China (Beijing) and Singapore regions, which deliver superior performance and higher stability for inference requests. We recommend that you migrate to the new domain names:
- China (Beijing) region: migrate from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore region: migrate from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
In this formula, {WorkspaceId} is your workspace ID, which you can view on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain names remain available.
HTTP synchronous call (wan2.6)
ImportantThe APIs in this section use the new protocol and support only the wan2.6 model.
You can obtain the result with a single request, making the process simple. It is recommended for most scenarios.
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
When making calls, replace {WorkspaceId} with your actual Workspace ID.
United States (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
When making calls, replace {WorkspaceId} with your actual Workspace ID.
The global deployment scope (Frankfurt region) supports only asynchronous calls.
Request parametersRequest headersContent-Type The request content type. This parameter must be set to Authorization Request authentication. The API uses an Alibaba Cloud Model Studio API Key for authentication. Example value: Bearer sk-xxxx. Request bodymodel Model name. Example value: wan2.6-t2i. NoteFor models of wan2.5 and earlier versions, see HTTP asynchronous calls for HTTP invocation. input Basic input information. parameters Image processing parameters. | text-to-image |
Response parametersoutput Task output information. usage The statistics of the output information. Only successful results are counted. request_id The unique request identifier. It can be used for request detail tracing and troubleshooting. code The error code returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. message The detailed error information returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. | Task executed successfullyTask data (such as task status and image URLs) is retained for only 24 hours and is automatically cleared after it expires. Please save the generated images in a timely manner. Task execution exceptionIf the task fails for any reason, the relevant information will be returned, and the code and message fields clearly indicate the cause of the error. See Error codes for troubleshooting. |
HTTP asynchronous calls (wan2.6)
ImportantThe APIs in this section use the new protocol and support only the wan2.6 model.
The task workflow consists of two core steps: "create task -> poll for results", as described below:
Step 1: Create a task to obtain the task ID
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
When making calls, replace {WorkspaceId} with your actual Workspace ID.
United States (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Note
- After the task is created successfully, use the
task_idreturned by the API to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks; simply poll for the results. - For a beginner's guide, see Postman.
Request parametersRequest headersContent-Type The request content type. This parameter must be set to Authorization Request authentication. The API uses an Alibaba Cloud Model Studio API Key for authentication. Example value: Bearer sk-xxxx. X-DashScope-Async The asynchronous processing configuration parameter. HTTP requests support asynchronous calls only, and it must be set to ImportantIf this request header is missing, the following error is returned: "current user api does not support synchronous calls". Request bodymodel Model name. Example value: wan2.6-t2i. NoteFor models of wan2.5 and earlier versions, see HTTP asynchronous calls for HTTP invocation. input Basic input information. parameters Image processing parameters. | text-to-image |
Response parametersoutput Task output information. request_id The unique request identifier. It can be used for request detail tracing and troubleshooting. code The error code returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. message The detailed error information returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. | Success responseSave the task_id, which is used to query the task status and results. Error responseTask creation failed. See Error codes for troubleshooting. |
Step 2: Query the result by task ID
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
When making calls, replace {WorkspaceId} with your actual Workspace ID.
United States (Virginia)
GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Beijing)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Germany (Frankfurt)
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Note
- Polling recommendations: Image generation takes a long time. We recommend that you use a polling mechanism and set an appropriate query interval (for example, 10 seconds) to obtain the results.
- Status transitions: PENDING (Queuing) → RUNNING (Processing) → SUCCEEDED (Success) / FAILED (Failed).
- Result URL: After the task succeeds, the image URL is returned and is valid for 24 hours. We recommend that you download the image immediately after you obtain the URL and store it in permanent storage (such as Alibaba Cloud OSS).
Request parametersRequest headersAuthorization Request authentication. The API uses an Alibaba Cloud Model Studio API Key for authentication. Example value: Bearer sk-xxxx. URL path parameterstask_id The task ID. | Query task resultReplace |
Response parametersoutput Task output information. usage Output statistics. Only successful results are counted. request_id The unique request identifier. It can be used for request detail tracing and troubleshooting. code The error code returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. message The detailed error information returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. | Task executed successfullyTask data (such as task status and image URLs) is retained for only 24 hours and is automatically cleared after it expires. Please save the generated images in a timely manner. Task execution exceptionIf the task fails for any reason, the relevant information will be returned, and the code and message fields clearly indicate the cause of the error. See Error codes for troubleshooting. |
HTTP Asynchronous Call (models at wan2.5 or earlier versions)
ImportantThis API uses the legacy protocol and supports only models at wan2.5 or earlier versions.
Because text-to-image tasks take a long time (usually 1 to 2 minutes), the API uses asynchronous calls. The entire process consists of "Create task -> Poll for results", two core steps, as follows:
The actual time required depends on the number of queued tasks and service execution. Please wait patiently when obtaining the results.
Step 1: Create a task to obtain the task ID
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Beijing
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Note
- After the task is created successfully, use the
task_idreturned by the API to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks; simply poll for the results. - For a beginner's guide, see Postman.
Request parametersRequest headersContent-Type The request content type. This parameter must be set to Authorization Request authentication. The API uses an Alibaba Cloud Model Studio API Key for authentication. Example value: Bearer sk-xxxx. X-DashScope-Async The asynchronous processing configuration parameter. HTTP requests support asynchronous calls only, and it must be set to ImportantIf this request header is missing, the following error is returned: "current user api does not support synchronous calls". Request Bodymodel The model name. For text-to-image models, see Models. Example value: wan2.5-t2i-preview. NoteFor HTTP calls to wan2.6 models, see HTTP synchronous call and HTTP asynchronous call. input Basic input information, such as prompts. parameters Image processing parameters, such as setting the image resolution, enabling smart prompt rewriting, and adding a watermark. | text-to-image
When calling, replace Text-to-image (using a negative prompt)Use negative_prompt to specify that the generated image should avoid the element "people".
When calling, replace |
Response parametersoutput Task output information. request_id The unique request identifier. It can be used for request detail tracing and troubleshooting. code The error code returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. message The detailed error information returned when the request fails. This parameter is not returned when the request succeeds. For details, see Error codes. | Success responseSave the task_id, which is used to query the task status and results. Error responseTask creation failed. See Error codes for troubleshooting. |
Step 2: Query the result by task ID
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
When making calls, replace {WorkspaceId} with your actual Workspace ID.
China (Beijing)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Note
- Polling recommendations: Image generation takes a long time. We recommend that you use a polling mechanism and set an appropriate query interval (for example, 10 seconds) to obtain the results.
- Status transitions: PENDING (Queuing) → RUNNING (Processing) → SUCCEEDED (Success) / FAILED (Failed).
- Result URL: After the task succeeds, the image URL is returned and is valid for 24 hours. We recommend that you download the image immediately after you obtain the URL and store it in permanent storage (such as Alibaba Cloud OSS).
Request parametersRequest headers (Headers)Authorization Request authentication. The API uses an Alibaba Cloud Model Studio API Key for authentication. Example value: Bearer sk-xxxx. URL path parameters (Path parameters)task_id The task ID. | Query task resultReplace
|
Response parametersoutput Task output information. usage The statistics of the output information. Only successful results are counted. request_id The unique request identifier. It can be used for request detail tracing and troubleshooting. | Task executed successfullyThe image URL is retained for only 24 hours and is automatically cleared after it expires. Save the generated images in a timely manner. Task execution failedIf a task fails, task_status is set to FAILED, with an error code and message provided. See Error codes for troubleshooting. Partial task failureThe model can generate multiple images in a single task. As long as one image is generated successfully, the task status will be marked as Task query expiredA task_id can be queried within 24 hours. After that, the query fails and the following error message is returned. |
Call via DashScope Python SDK
The SDK parameter names are basically the same as those of the HTTP API, and the parameter structure is encapsulated according to language-specific features.
Since text-to-image tasks are time-consuming, the SDK encapsulates the HTTP asynchronous call process at the underlying layer and supports both synchronous and asynchronous call methods.
The actual time required depends on the number of queued tasks and service execution. Please wait patiently when obtaining the results.
wan2.6
Important
- The following code applies only to the wan2.6 model.
- Make sure the DashScope Python SDK version is no earlier than
2.0.1before running the following code. For updates, see Install SDK.
The region and API Key are not interchangeable across regions. The following examples use the Singapore region as an example:
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
United States (Virginia)
https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Germany (Frankfurt)
https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
The global deployment scope (Frankfurt region) supports asynchronous calls only.
Synchronous call
Request example
import os
import dashscope
# The following is the configuration for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is region-specific. To obtain an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
print("----sync call, please wait a moment----")
# generate is a one-step call (submits the task and waits for completion), returning a completed Job
job = client.images.generate(
model="wan2.6-t2i",
prompt='一间有着精致窗户的花店,漂亮的木质门,摆放着花朵',
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
print(job)
print(job.image_urls)
Response example
The url is valid for 24 hours. Download the image in a timely manner.
{
"request_id": "820dd0db-eb42-4e05-8d6a-1ddb4axxxxxx",
"task_id": "f470bbfd-d955-4165-935b-d35b8eexxxxxx",
"status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx"
}
],
"usage": {
"image_count": 1,
"size": "1280*1280"
}
}
Asynchronous call
Request example
import os
import dashscope
from dashscope import DashScopeError
# The following is the configuration for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Create an asynchronous task
def create_async_task():
print("Creating async task...")
job = client.images.jobs.create(
model="wan2.6-t2i",
prompt='一间有着精致窗户的花店,漂亮的木质门,摆放着花朵',
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
print("Task created successfully:", job)
return job
# Wait for the task to complete (polling with exponential backoff, 24-hour total budget by default; a FAILED task raises DashScopeError)
def wait_for_completion(task):
print("Waiting for task completion...")
done = client.images.jobs.wait(task)
print("Task succeeded!")
print("Response:", done)
print("Image URLs:", done.image_urls)
# Fetch asynchronous task information
def fetch_task_status(task):
print("Fetching task status...")
status = client.images.jobs.fetch(task)
print("Task status:", status.status)
# Cancel the asynchronous task
def cancel_task(task):
print("Canceling task...")
response = client.images.jobs.cancel(task)
print("Task canceled successfully:", response.status)
# Main execution flow
if __name__ == "__main__":
try:
task = create_async_task()
wait_for_completion(task)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://www.alibabacloud.com/help/model-studio/error-code")
Response example
- Response example for creating a task
{
"request_id": "c4f11410-ea42-4996-957d-9c82f9xxxxxx",
"task_id": "f470bbfd-d955-4165-935b-d35b8eexxxxxx",
"status": "PENDING"
}
- Response example for querying node results
The url is valid for 24 hours. Download the image in a timely manner.
{
"request_id": "7e57e7e8-00b0-4534-9aff-fe31e0xxxxxx",
"task_id": "f470bbfd-d955-4165-935b-d35b8exxxxxx",
"status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx"
}
],
"usage": {
"image_count": 1,
"size": "1280*1280"
}
}
Models at wan2.5 and earlier versions
Important
-
The following code applies only to models at wan2.5 and earlier versions.
-
Make sure the DashScope Python SDK version is no lower than
2.0.1before running the following code.For updates, see Install SDK.
The region and API Key are not interchangeable across regions. The following examples use the Singapore region as an example:
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Synchronous call
Request example
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
import os
import dashscope
from dashscope import DashScopeError
# The following is the configuration for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
print('----sync call, please wait a moment----')
try:
# generate is a one-step call (submits the task and waits for completion), returning a completed Job
job = client.images.generate(
model="wan2.5-t2i-preview",
prompt="一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345
)
print('response: %s' % job)
# Save the image in the current directory
for url in job.image_urls:
file_name = PurePosixPath(unquote(urlparse(url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(url).content)
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://www.alibabacloud.com/help/model-studio/error-code")
Response example
The url is valid for 24 hours. Download the image in a timely manner.
{
"request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
"task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
"orig_prompt": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
"actual_prompt": "一间精致的花店,窗户上装饰着优雅的雕花,漂亮的木质门上挂着铜制把手。店内摆放着各种色彩鲜艳的花朵,如玫瑰、郁金香和百合等。背景是温馨的室内场景,光线柔和,营造出宁静舒适的氛围。高清写实摄影,近景中心构图。"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"image_count": 1
}
}
Asynchronous call
Request example
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
import os
import dashscope
from dashscope import DashScopeError
# The following is the configuration for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
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():
job = client.images.jobs.create(
model="wan2.5-t2i-preview",
prompt="一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345
)
print(job)
print(job.task_id, job.status)
return job
# Wait for the asynchronous task to finish (polling with exponential backoff, 24-hour total budget by default; a FAILED task raises DashScopeError)
def wait_async_task(task):
done = client.images.jobs.wait(task)
print(done)
# save file to current directory
for url in done.image_urls:
file_name = PurePosixPath(unquote(urlparse(url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(url).content)
# Fetch asynchronous task information
def fetch_task_status(task):
status = client.images.jobs.fetch(task)
print(status)
print(status.status)
# Cancel the asynchronous task. Only tasks in the PENDING state can be canceled.
def cancel_task(task):
rsp = client.images.jobs.cancel(task)
print(rsp)
print(rsp.status)
if __name__ == '__main__':
try:
async_call()
except DashScopeError as e:
print(f"HTTP返回码:{e.status_code}")
print(f"错误码:{e.code}")
print(f"错误信息:{e.message}")
print("请参考文档:https://www.alibabacloud.com/help/model-studio/error-code")
Response example
- Response example for creating a task
{
"request_id": "31b04171-011c-96bd-ac00-f0383b669cc7",
"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
"status": "PENDING"
}
- Response example for querying node results
The url is valid for 24 hours. Download the image in a timely manner.
{
"request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
"task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png",
"orig_prompt": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
"actual_prompt": "一间精致的花店,窗户上装饰着优雅的雕花,漂亮的木质门上挂着铜制把手。店内摆放着各种色彩鲜艳的花朵,如玫瑰、郁金香和百合等。背景是温馨的室内场景,光线柔和,营造出宁静舒适的氛围。高清写实摄影,近景中心构图。"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"image_count": 1
}
}
Call the DashScope Java SDK
The SDK parameter names are basically the same as those of the HTTP API, and the parameter structure is encapsulated according to language-specific features.
Since text-to-image tasks are time-consuming, the SDK encapsulates the HTTP asynchronous call process at the underlying layer and supports both synchronous and asynchronous call methods.
The actual time required depends on the number of queued tasks and service execution. Please wait patiently when obtaining the results.
wan2.6
Important
- The following code applies only to the wan2.6-t2i model.
- Make sure the DashScope Java SDK version is no lower than
2.22.6before running the following code.
The base_url and API Key are not interchangeable across regions. The following examples use the Singapore region as an example:
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
United States (Virginia)
https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Germany (Frankfurt)
https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
The global deployment scope (Frankfurt region) supports asynchronous calls only.
Synchronous call
Request example
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
// 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 各地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
Response example
The url is valid for 24 hours. Download the image in a timely manner.
{
"status_code": 200,
"request_id": "50b57166-eaaa-4f17-b1e0-35a5ca88672c",
"code": "",
"message": "",
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
"type": "image"
}
]
}
}
],
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"image_count": 1,
"size": "1280*1280",
"total_tokens": 0
}
}
Asynchronous call
Request example
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
// 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 各地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---async call, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
// 等待任务完成
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}
Response example
- Response example for creating a task
{
"status_code": 200,
"request_id": "9cd85950-2e26-4b2c-b562-1694cf9288e5",
"code": "",
"message": "",
"output": {
"task_id": "4c861fbe-af89-4a2f-8fc5-4bb15c3139ba",
"task_status": "PENDING"
},
"usage": null
}
- Response example for querying node results
The url is valid for 24 hours. Download the image in a timely manner.
{
"status_code": 200,
"request_id": "cbdf1424-306e-4a52-82f3-8bf5d8a99103",
"code": "",
"message": "",
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
"type": "image"
}
]
}
}
],
"task_id": "4c861fbe-af89-4a2f-8fc5-4bb15c3139ba",
"task_status": "SUCCEEDED",
"submit_time": "2026-01-16 16:36:06.556",
"scheduled_time": "2026-01-16 16:36:06.591",
"end_time": "2026-01-16 16:36:25.190",
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"size": "1280*1280",
"total_tokens": 0,
"image_count": 1
}
}
Models at wan2.5 and earlier versions
Important
-
The following code applies only to models at wan2.5 and earlier versions.
-
Make sure the DashScope Java SDK version is no lower than
2.22.2before running the following code.If the version is too low, errors such as "url error, please check url!" may occur. Refer to Install SDK to update.
The base_url and API Key are not interchangeable across regions. The following examples use the Singapore region as an example:
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
When making calls, replace {WorkspaceId} with your actual Workspace ID.
Synchronous call
Request example
// 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;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 新加坡和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException {
// 设置parameters参数
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("一间有着精致窗户的花店,漂亮的木质门,摆放着花朵")
.n(1)
.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.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();
param.setApiKey(apiKey);
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
// If set DASHSCOPE_API_KEY environment variable, apiKey can null.
ImageSynthesisResult result = is.fetch(taskId, apiKey);
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());
}
}
}
Response example
The url is valid for 24 hours. Download the image in a timely manner.
{
"request_id": "22f9c744-206c-9a78-899a-xxxxxx",
"output": {
"task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"orig_prompt": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
"actual_prompt": "一间有着精致雕花窗户的花店,漂亮的深色木质门微微敞开。店内摆放着各式各样的鲜花,包括玫瑰、百合和向日葵,色彩鲜艳,香气扑鼻。背景是温馨的室内场景,光线柔和,透过窗户洒在花朵上。高清写实摄影,中景构图。",
"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 call
Request example
// 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;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 新加坡和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
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);
}
/**
* 创建异步任务
* @return taskId
*/
public String createAsyncTask() {
// 设置parameters参数
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("一间有着精致窗户的花店,漂亮的木质门,摆放着花朵")
.n(1)
.size("1280*1280)
.negativePrompt("")
.parameters(parameters)
.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;
}
/**
* 等待异步任务结束
* @param taskId 任务id
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
//环境变量配置后,可在这里将apiKey设置为null
result = imageSynthesis.wait(taskId, apiKey);
} 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();
}
}
Response example
- Response example for creating a task
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}
- Response example for querying node results
{
"request_id": "22f9c744-206c-9a78-899a-xxxxxx",
"output": {
"task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"orig_prompt": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵",
"actual_prompt": "一间有着精致雕花窗户的花店,漂亮的深色木质门微微敞开。店内摆放着各式各样的鲜花,包括玫瑰、百合和向日葵,色彩鲜艳,香气扑鼻。背景是温馨的室内场景,光线柔和,透过窗户洒在花朵上。高清写实摄影,中景构图。",
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
}],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}
Limits
- Data validity: The task
task_idand imageurlare retained for only 24 hours, after which they can no longer be queried or downloaded. - Content moderation: Both the input
promptand the output images go through content safety review. Requests containing non-compliant content will return the "IPInfringementSuspect" or "DataInspectionFailed" error. For more information, see Error codes.
Billing and rate limits
- For the model free quota and billing unit prices, see the Model Studio console.
- For model rate limits, see Wan.
- Billing details: You are billed based on the number of images successfully generated. Failed model calls or processing errors do not incur any fees and do not consume the new-user free quota.
Error codes
If a model call fails and returns an error message, see Error codes for troubleshooting.