Call image and video generation APIs with Postman and cURL

Use Postman or cURL to call image or video generation APIs in Model Studio. Using text-to-image as an example, this guide shows how to create a task and retrieve the result.

Postman: A graphical HTTP client. Recommended for beginners.
cURL: A command-line tool for developers familiar with the terminal.

Note

Postman and cURL are for testing only. For production, use the official SDK or build your own HTTP client.

How asynchronous calls work

Image and video generation can take tens of seconds to several minutes. To avoid HTTP timeouts, the API uses an asynchronous pattern:

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. Once the task is complete, you can retrieve the final image or video URL.

HTTP call example (text-to-image)

Method 1: Send requests with Postman (recommended)

cURL to Postman mapping

cURL parameters map to Postman as follows:

cURL parameter	Postman UI	Description
`curl -X POST` or `curl -X GET`	Request method drop-down list	HTTP method.
`https://`	URL input field	API request URL.
`-H 'Key: Value'`	Headers Tab	Request headers as key-value pairs.
`-d '{...}'`	Body Tab	Request body.

Prerequisites

Before calling the API, you must get an API key for your region and download Postman to your local machine.

Step 1: Create a task

Configure the Postman request based on this cURL command.

The following base_url is for the Singapore region. You must use the base_url that corresponds to your region.

HELPCODEESCAPE-curl
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.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 new or + to create an HTTP request.
Set the method to POST and enter the API URL for your target region:
- Singapore: https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- US (Virginia): https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- China (Beijing): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
For supported models, see the Model Studio console. Region and service scope are determined by system-preset binding relationships and cannot be freely combined.
Click the Headers tab and add these key-value pairs.

Key	Value	Description
X-DashScope-Async	enable	Enables an asynchronous call.
Authorization	Bearer sk-xxx (replace sk-xxx with your API key)	Authentication credential.
Content-Type	application/json	JSON request body.

Configure the request body.

Click the Body tab, select raw , then select JSON from the format drop-down, and paste the JSON content after -d in the cURL example.

HELPCODEESCAPE-json
{
    "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 to format the JSON.

Click Send to get the task_id. The task_id is valid for 24 hours. Download the result before it expires.

Step 2: Query the task result

After you get the task_id, call the query endpoint to retrieve the final result.

Singapore: https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
US (Virginia): https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}
China (Beijing): https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

HELPCODEESCAPE-curl
curl -X GET https://dashscope-intl.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. Enter the query URL for your region, replacing {task_id} with the task ID from Step 1.
4. In the Headers tab, add the Authorization header with the same API key as Step 1.
5. Click Send to send the request.
Check the response. Poll until task_status is SUCCEEDED. The response then contains the image URL, valid for 24 hours. Download it before it expires.

Method 2: Send requests with cURL

Use cURL to test the API from the command line.

Prerequisites

Before running the cURL commands:

Enable the model service and get an API key.
Ensure cURL is installed, and configure the API key as an environment variable to reference $DASHSCOPE_API_KEY.
Check if cURL is installed Check if cURL is installed:
```
HELPCODEESCAPE-bash
curl --version
```
If you see output similar to the following, cURL is installed:
```
HELPCODEESCAPE-plaintext
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 may see a message similar to 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:

The following base_url is for the Singapore region. You must use the base_url that corresponds to your region.

HELPCODEESCAPE-curl
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.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, valid for 24 hours. Download the result before it expires.

Step 2: Query the task result

Replace {task_id} in the following command with the task ID from Step 1, then run it.
The following base_url is for the Singapore region. You must use the base_url that corresponds to your region.
```
HELPCODEESCAPE-curl
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
```
When task_status is SUCCEEDED, the response includes an image URL, valid for 24 hours. Download it before it expires.
Processing takes tens of seconds to several minutes. Poll the API every 3 to 5 seconds until task_status is no longer RUNNING.

Next steps

After generating your first image:

Explore API parameters : See the text-to-image API reference for all available parameters.
Try video generation : Call the first-frame-to-video API to generate a video.
Browse more models: Visit the Model Studio console for all supported image and video models.

Call image and video generation APIs with Postman and cURL ​

How asynchronous calls work ​

Method 1: Send requests with Postman (recommended) ​

cURL to Postman mapping ​

Prerequisites ​

Step 1: Create a task ​

Step 2: Query the task result ​

Method 2: Send requests with cURL ​

Prerequisites ​

Step 1: Create a task ​

Step 2: Query the task result ​

Next steps ​

Call image and video generation APIs with Postman and cURL

How asynchronous calls work

Method 1: Send requests with Postman (recommended)

cURL to Postman mapping

Prerequisites

Step 1: Create a task

Step 2: Query the task result

Method 2: Send requests with cURL

Prerequisites

Step 1: Create a task

Step 2: Query the task result

Next steps