Use Postman or cURL to call image and video generation APIs

Postman: An intuitive, graphical tool for testing HTTP requests. Recommended for beginners.
cURL: A powerful command-line tool for developers comfortable with the command line.

Postman and cURL are intended for quick testing and functional verification. For production environments, use the official SDKs or implement your own HTTP calls.

Asynchronous call mechanism

Image and video generation tasks can take a long time to complete, ranging from over ten seconds to several minutes. To avoid long-running HTTP connections and timeouts, the API uses an asynchronous call mechanism. The process is divided into two steps:

Create a task: Call the API to create a task. The service synchronously returns a task ID (task_id).
Query the result: Use the task ID to poll the task status until the task is complete, and then retrieve the final image or video URL.

HTTP call example (text-to-image)

Method 1: Use Postman (recommended)

Configure Postman from cURL

When converting a cURL command to a Postman request, the parameters map as follows:

cURL parameter	Postman UI	Description
`curl -X POST` or `curl -X GET`	Request method drop-down	Selects the HTTP request method.
`https://<api-endpoint-url>`	URL input box	The API endpoint URL.
`-H 'Key: Value'`	Headers tab	Configures request headers as key-value pairs.
`-d '{...}'`	Body tab	Configures the request body.

Prerequisites

Before you call the API, obtain an API key for your region and download Postman.

Step 1: Create a task

Use the following cURL command to configure Postman.

The following base URL is for the Singapore region. You must use the corresponding base URL for your region.

curl -X POST https://{WorkspaceId}.ap-southeast-1.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": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

In Postman, click the new or + button to create a new request, and select HTTP as the request type.
From the request method drop-down, select POST and enter the URL for your model's deployment region:
- Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis, and replace WorkspaceId with your actual Workspace ID as described in Obtain Workspace ID.
- US (Virginia): https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- China (Beijing): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
For the models supported in each region, see the Model Studio console. The current region and service deployment scope are based on the predefined system binding relationships, and custom combinations are not supported.

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

Click the Headers tab and add the following three key-value pairs.

Key	Value	Description	In Postman, on the Headers tab, set X-DashScope-Async to `enable`, Authorization to `Bearer <your-api-key>`, and Content-Type to `application/json`.
X-DashScope-Async	enable	Enables asynchronous calls.
Authorization	Bearer sk-xxx (Replace sk-xxx with your API key)	Authentication credential.
Content-Type	application/json	Declares that the request body is in JSON format.

Configure the request body:
- Click the Body tab, select the raw radio button, select JSON from the format drop-down menu on the right, and then paste the JSON content that follows -d from the cURL example into the input box.

{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

(Optional) Click Beautify on the right side of the page to format the JSON and make it easier to read.

Click Send to send the request and obtain the task_id. The task_id is valid for 24 hours. After this period, the result cannot be queried. Please retrieve the result promptly.

{
    "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
    "output": {
        "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
        "task_status": "PENDING"
    }
}

Step 2: Query result by task ID

Once you have the task ID, call the query endpoint to retrieve the final result.

Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis, and replace WorkspaceId with your actual Workspace ID.
US (Virginia): https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
China (Beijing): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Configure the query request in Postman:
1. Create a new HTTP request.
2. Set the request method to GET.
3. Based on the region, enter the query URL, and replace {task_id} in the URL with the actual task_id that you obtained in Step 1.
4. In the Headers tab, add the Authorization header, using the same API key from Step 1.
5. Click Send.

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/42442de9-917d-4c41-80a7-37fb7ad25ed2

Headers:
Cookie: acw_tc=896b2ccd-a0cd-40a8-a557-bb73cee5cf957...
Postman-Token: <calculated when request is sent>
Host: <calculated when request is sent>
User-Agent: PostmanRuntime/7.49.1
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Authorization: Bearer sk-xxx

Check the response. Poll this endpoint until the task_status is SUCCEEDED to get the image URL. The image URL is valid for 24 hours. Be sure to download the image within the 24-hour validity period.

"results": [
            {
                "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
                "actual_prompt": "A cozy and elegant flower shop, with an exterior decorated with exquisitely carved windows. The window frames are light-colored wood, set with transparent glass that reveals the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate, giving it a quaint and textured feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including roses, lilies, hydrangeas, and tulips—are arranged in a staggered, vibrant display. Some bouquets are wrapped in kraft paper and tied with twine, exuding a fresh, natural scent. The background features a quiet European town streetscape, with stone-paved roads and greenery adding to the charm. The overall image is in a realistic photographic style, with soft lighting and a warm color palette that highlights the shop's exquisite and romantic atmosphere.",
                "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/3a/20251203/7a2bee47/42442de9-917d-4c41-80a7-37fb7ad25ed2.png?xxx"
            }
        ]

Method 2: Use cURL

Developers familiar with the command line can use cURL to quickly test the API.

Prerequisites

Before you run the cURL command:

Activate the model service and obtain an API key.
Ensure that you have installed cURL, and configure the API key as an environment variable, so you can directly reference the $DASHSCOPE_API_KEY variable later.
Check if cURL is installed
Run the following command to check if cURL is installed.
curl --version
If you see output similar to the following, cURL is installed:
curl 8.x.x (x86_64-apple-darwin23.0) libcurl/8.x.x (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.58.0 Release-Date: 2023-10-11 Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: alt-svc AsynchDNS GSS-API HSTS HTTP2 HTTPS-proxy IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL threadsafe UnixSockets
If it is not installed, you might see a message like one of the following:
- Windows: 'curl' is not recognized as an internal or external command, operable program or batch file.
- Linux/macOS: command not found: curl.
Go to the curl download page to install it.

Step 1: Create a task

Run the following command in your terminal:
The following base URL is for the Singapore region. You must use the corresponding base URL for your region.

curl -X POST https://{WorkspaceId}.ap-southeast-1.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": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

A successful request returns a task_id. The ID is valid for 24 hours and cannot be used for queries after it expires. Please retrieve the result promptly.

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": "wan2.5-t2i-preview",
    "input": {
        "prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
{"request_id":"ca3b5224-bc60-4e47-80f4-2790040e9e55","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d318061c43","task_status":"PENDING"}}

Step 2: Query result by task ID

Replace {task_id} in the following command with the task ID that you obtained in Step 1, copy the command to the terminal, and execute it.
The following base URL is for the Singapore region. You must use the corresponding base URL for your region.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

When the task is complete (the task_status is SUCCEEDED), the response will contain an image URL. The image URL is valid for 24 hours. Download it promptly.
Because the model takes a long time to process (from tens of seconds to several minutes), you may need to poll this API. We recommend that you query the API every 3 to 5 seconds until the task_status is no longer RUNNING.

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"24143559-9964-4898-8f9c-d968bba182b9","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d3f8061c43","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:19:18.293","scheduled_time":"2025-12-03 10:19:18.320","end_time":"2025-12-03 10:19:31.890","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A cozy, elegant flower shop. The exterior wall features exquisitely carved windows with dark brown wooden frames, and the glass is clean and bright, revealing the soft light inside. The front door is a beautiful solid wood door that retains its natural grain, complemented by a brass handle and a vintage nameplate that exudes a strong artisanal feel. On both sides of the front steps, and on the windowsills and entrance area, various flowers—including blooming roses, elegant hydrangeas, fresh daisies, and green eucalyptus leaves—are arranged in a staggered yet harmonious display. The background is a quiet European town streetscape, with a stone-paved road and a vine-covered neighboring wall enhancing the romantic atmosphere. The overall image is in a realistic photographic style, with soft, natural lighting that highlights the wood texture and floral details.","url":"https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/59/20251203/7a2bee47/2de3f7e1-52ce-4cf4-a466-f2d3f8061c43.png?Expires=1764814771&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/8b108773-4e7d-4cd7-8c62-aad7a08d7769 \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
{"request_id":"0ee9ab8a-0ea4-9f0b-9cb0-41eaf24fd5e8","output":{"task_id":"8b108773-4e7d-4cd7-8c62-aad7a08d7769","task_status":"SUCCEEDED","submit_time":"2025-12-03 10:50:24.253","scheduled_time":"2025-12-03 10:50:24.282","end_time":"2025-12-03 10:50:42.708","results":[{"orig_prompt":"A flower shop with exquisite windows, a beautiful wooden door, and flowers on display","actual_prompt":"A warm and elegant flower shop, with an exterior wall decorated with an exquisitely carved window. The window frame is dark brown solid wood, with clean and bright glass revealing the soft light inside. The front door is a beautiful wooden door crafted with a vintage distressed technique, its surface retaining the wood grain texture, complemented by a brass door handle and a small nameplate decoration, exuding a strong handmade feel. In front of the door, on the windowsill, and on both sides of the entrance, various flowers are arranged in a staggered fashion—pink and white roses, pale purple hydrangeas, bright yellow sunflowers, and green eucalyptus leaves—with soft and layered colors. The background is a quiet European-style street, with cobblestones and vine-covered neighboring walls adding a romantic atmosphere. The overall image is in a realistic photography style, with warm and natural lighting, highlighting the tranquility and beauty of the flower shop.","url":"https://dashscope-result-sgp.oss-ap-southeast-1.aliyuncs.com/1d/63/20251203/c3a8f0e2/24817593-8b108773-4e7d-4cd7-8c62-aad7a08d7769.png?Expires=1748416642&OSSAccessKeyId=YOUR_ACCESS_KEY_ID"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}%

Next steps

After you have successfully generated your first image, you can explore the following:

Learn more about API parameters: See the text-to-image API documentation to learn about additional parameters.
Try video generation: Try the first-frame-to-video API to create a video.
Explore more models: Go to the Model Studio console to see all image and video models supported by Alibaba Cloud Model Studio (Bailian).

​Asynchronous call mechanism

​Method 1: Use Postman (recommended)

​Prerequisites

​Step 1: Create a task

​Step 2: Query result by task ID

​Method 2: Use cURL

​Prerequisites

​Step 1: Create a task

​Step 2: Query result by task ID

​Next steps

Asynchronous call mechanism

Method 1: Use Postman (recommended)

Prerequisites

Step 1: Create a task

Step 2: Query result by task ID

Method 2: Use cURL

Prerequisites

Step 1: Create a task

Step 2: Query result by task ID

Next steps