Use Postman or cURL to call image and video generation APIs

HTTP call example (text-to-image)

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 China (Beijing) region. You must use the corresponding base URL for your region.

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
    }
}'

1. In Postman, click the new or + button to create a new request, and select HTTP as the request type.

2. From the request method drop-down, select POST and enter the URL for your model's deployment region:

   • China (Beijing): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

   • Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis. Replace WorkspaceId with your actual Workspace ID.

   • US (Virginia): https://dashscope-us.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.

3. 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.

4. 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.

5. 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.

• China (Beijing): https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

• Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis. Replace WorkspaceId with your actual Workspace ID. For more information, see Get Workspace ID.

• US (Virginia): https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

1. 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.

2. 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"
               }
           ]

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 China (Beijing) region. You must use the corresponding base URL for your region.

  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
      }
  }'

• 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 China (Beijing) region. You must use the corresponding base URL for your region.

  curl -X GET https://dashscope.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=xxx"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}