How to use Postman or cURL to make HTTP requests? - Alibaba Cloud Model Studio

This topic explains how to use Postman and cURL to call image or video generation APIs in Alibaba Cloud Model Studio. We use text-to-image as an example to show the complete flow, from creating a task to getting the result.

Postman: A graphical HTTP testing tool with an intuitive interface. Recommended for beginners.
cURL: A powerful command-line tool for developers who are familiar with command-line interfaces.

Note

Postman and cURL are designed for quick testing and feature validation only. In production environments, use the official SDK or implement your own HTTP calls.

Asynchronous API call mechanism

Image and video generation tasks can be time-consuming, taking anywhere from tens of seconds to several minutes. To prevent long waits and HTTP connection timeouts, the APIs use an asynchronous call mechanism. This process involves 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. Once the task is complete, you can retrieve the URL of the final image or video.

HTTP call example (text-to-image)

Method 1: Send requests using Postman (recommended)

How to configure Postman from a cURL command?

When you convert a cURL example to a Postman request, the parameters correspond as follows:

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

Prerequisites

Before calling the API, create an API key for your region and download Postman.

Step 1: Create a task

Configure Postman based on the following cURL command.

The following base_url is for the Singapore region. If you use a model in the China (Beijing) region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis.

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 the new or + to create a new request. Select HTTP as the request type.
From the request method drop-down menu, select POST and enter the URL for your model's region:
- International (Singapore) region: https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- China (Beijing) region: https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

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

Key	Value	Description
X-DashScope-Async	enable	Enables asynchronous invocation.
Authorization	Bearer sk-xxx (Replace sk-xxx with your Model Studio API key)	Identity verification credential.
Content-Type	application/json	Declares that the request body is in JSON format.

Configure the request body (Body)
- Click the Body tab, select the raw radio button, and then select JSON from the format drop-down menu on the right. Paste the JSON content that follows -d in 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 for better readability.
Click Send to send the request and retrieve the task_id. The ID is valid for 24 hours. After it expires, you cannot query the task. Retrieve the result promptly.

Step 2: Query the result by task_id

After you get the task_id, use the query API to retrieve the final result.

The following base_url is for the Singapore region. If you use a model in the China (Beijing) region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}.

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. Replace {task_id} in the URL with the actual task_id that you got in Step 1.
4. On the Headers tab, add the Authorization key. Use the same API key value as in Step 1.
5. Click Send to send the request.
Check the returned result. Repeatedly send this request (polling) until `task_status` changes to `SUCCEEDED`, and then retrieve the image URL. The image URL is valid for 24 hours. Download it promptly.

Method 2: Send requests using cURL

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

Prerequisites

Before you run the cURL command:

Activate Model Studio and get an API key.
Make sure that cURL is installed on your system and you have exported the API key as an environment variable. This lets you directly reference the $DASHSCOPE_API_KEY variable.
Check if cURL is installed
Run the following command to check if cURL is installed.
```
curl --version
```
If you receive 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 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.
Visit 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. If you use a model in the China (Beijing) region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis.

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. The ID is valid for 24 hours. After it expires, you can no longer query the task. Retrieve the result promptly.

Step 2: Query the result by task_id

Replace {task_id} in the following command with the task ID that you got in Step 1. Then, copy the command to your terminal and run it.
The following base_url is for the Singapore region. If you use a model in the China (Beijing) region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}.
```
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
```
When the task_status is SUCCEEDED, the response contains the image URL. The image URL is valid for 24 hours. Download the image before the URL expires.
Processing the task can take from tens of seconds to several minutes. You may need to poll this endpoint. Query the endpoint every 3 to 5 seconds until the task_status is no longer RUNNING.

Next steps

After you generate your first image, explore the following options:

Learn more about API parameters: See text-to-image API reference to learn more about input and output parameters.
Try video generation: Call the first-frame-to-video API to create dynamic videos.
Browse more models: Visit the Model list to view all image and video models supported by Model Studio.