Skip to main content
接入用戶端/開發工具

使用Postman或cURL調用映像/視頻產生API

本文介紹使用 Postman 和 cURL 調用阿里雲百鍊的映像或視頻產生 API。以“ 文生圖 ”為例，示範從建立任務到擷取結果的完整流程。

  • Postman：一款介面化的 HTTP 測試載入器，操作直觀，推薦初學者使用。
  • cURL：一個強大的命令列工具，適用於熟悉命令列的開發人員。
Postman 和 cURL僅適用於快速測試與功能驗證。對於生產環境，建議您使用官方 SDK 或自行實現 HTTP 調用。

API非同步呼叫機制

由於映像與視頻產生任務耗時較長（十幾秒到數分鐘不等），為避免長時間的HTTP串連等待和逾時，API採用非同步呼叫機制。整個調用過程分為兩步：
  1. 建立任務：調用 API 建立任務，服務會同步返回一個任務 ID（task_id）。
  2. 查詢結果：使用該 task_id，通過輪詢方式查詢任務狀態，直到任務完成並擷取最終的映像或視頻 URL。
HTTP調用樣本（文生圖）

方式一：使用Postman發送請求（推薦）

將 cURL 樣本轉換為 Postman 請求時，各參數存在以下對應關係：

cURL參數

Postman 介面

說明

curl -X POST或curl -X GET

要求方法下拉框

選擇 HTTP 要求方法

https://<api-endpoint-url>

URL 輸入框

API 的請求地址

-H 'Key: Value'

Headers標籤頁

配置要求標頭，以 鍵 (Key) - 值 (Value) 的形式展示。

-d '{...}'

Body標籤頁

配置請求體

前提條件

在調用API之前，您需要根據地區擷取API Key，下載Postman到本地。

步驟1：建立任務

我們將根據下面的 cURL 命令來配置 Postman。
以下為新加坡地區的base_url，不同地區需配置對應的 base_url。 
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": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
  1. 在 Postman 中，單擊new或+ 按鈕建立一個新請求，請求類型選擇HTTP。
  2. 在要求方法下拉式功能表中選擇POST，並根據您的模型所在地區填入對應的 URL：
    • 新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis，請將WorkspaceId替換為真實的擷取Workspace ID
    • 美國（維吉尼亞）：https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
    • 華北2（北京）：https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
    各地區支援的模型請參見百鍊控制台，當前地區與服務部署範圍為系統預設綁定關係，不支援自由組合。 
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
  1. 點擊Headers標籤頁，添加以下三個索引值對。

    Key

    Value

    說明

    在 Postman 的 Headers 標籤頁中，配置以下關鍵要求標頭：X-DashScope-Async 設定為 enable，Authorization 設定為 Bearer <your-api-key>，Content-Type 設定為 application/json。

    X-DashScope-Async

    enable

    啟用非同步呼叫

    Authorization

    Bearer sk-xxx（請將sk-xxx替換為阿里雲百鍊API Key）

    身分識別驗證憑證

    Content-Type

    application/json

    聲明請求體為JSON格式

  2. 配置請求體 (Body)
    • 點擊 Body 標籤頁，選中 raw 單選框，然後在右側的格式下拉式功能表中選擇JSON，將cURL樣本中的 -d 後面的 JSON 內容粘貼到輸入框。
{
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}
  • （可選）點擊頁面右側的 Beautify，可以格式化JSON格式，使其更易閱讀。
  1. 點擊Send發送請求，並擷取 task_id。有效期間 24 小時，到期後無法查詢，請及時擷取結果。
{
    "request_id": "896b2ccd-a0cd-40a8-a557-bb73cee5cf95",
    "output": {
        "task_id": "42442de9-917d-4c41-80a7-37fb7ad25ed2",
        "task_status": "PENDING"
    }
}

步驟2：根據task_id查詢結果

擷取到 task_id 後，需要通過查詢介面來擷取最終結果。
  • 新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis，請將WorkspaceId替換為真實的擷取Workspace ID
  • 美國（維吉尼亞）：https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
  • 華北2（北京）：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"
  1. 在 Postman 中配置查詢請求：
    1. 建立一個HTTP請求。
    2. 配置要求方法為GET 。
    3. 根據地區，填入查詢URL，將URL中的 {task_id} 替換為在步驟1中擷取的真實 task_id。
    4. 在Headers標籤頁中，添加 Authorization 鍵，其值與步驟1中使用的 API Key 相同。
    5. 點擊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
  1. 檢查返回結果。重複發送此請求（輪詢），直到 task_status 變為 SUCCEEDED，擷取映像的URL。映像URL有效期間為24小時，請及時下載。
"results": [
            {
                "orig_prompt": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵",
                "actual_prompt": "一間溫馨雅緻的花店，外牆裝飾著精緻的雕花窗戶，窗框為淺色木質，鑲嵌著透明玻璃，透出店內柔和的光線。花店正門是一扇漂亮的實木門，表面保留了天然木紋，配以黃銅門把手和複古門牌，顯得古樸而有質感。門前台階兩側和店內窗檯、門口處錯落有致地擺放著各式鮮花——包括玫瑰、百合、繡球、鬱金香等，色彩繽紛、生機盎然。部分花束用牛皮紙包裹，系著麻繩，散發出自然清新的氣息。背景為寧靜的歐洲小鎮街景，石板路與綠植相映成趣。整體畫面採用寫實攝影風格，光線柔和，色調溫暖，突出花店的精緻與浪漫氛圍。",
                "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1d/3a/20251203/7a2bee47/42442de9-917d-4c41-80a7-37fb7ad25ed2.png?xxx"
            }
        ]

方式二：使用cURL發送請求

熟悉命令列的開發人員可使用cURL快速測試API。

前提條件

在執行cURL命令之前，您需要：
  • 已開通模型服務並擷取API Key。
  • 確保您的系統中已安裝 cURL，並配置API Key到環境變數，方便後續直接引用$DASHSCOPE_API_KEY變數。
    運行以下命令，檢查 cURL 是否已安裝。
    curl --version
    如果看到類似如下輸出，說明cURL已安裝：
    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
    如果沒有安裝，可能會給出以下類似提示：
    • Windows: 'curl' 不是內部或外部命令，也不是可啟動並執行程式或批次檔。
    • Linux/macOS: command not found: curl。
    請訪問curl下載頁面進行安裝，

步驟1：建立任務

  • 在終端執行以下命令：
    以下為新加坡地區的base_url，不同地區需配置對應的 base_url。 
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": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
  • 成功請求後將返回task_id。有效期間 24 小時，到期後無法查詢。請及時擷取結果。
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": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'
{"request_id":"ca3b5224-bc60-4e47-80f4-2790040e9e55","output":{"task_id":"2de3f7e1-52ce-4cf4-a466-f2d318061c43","task_status":"PENDING"}}

步驟2：根據task_id查詢結果

  • 將以下命令中的 {task_id} 替換為步驟 1 中擷取的任務 ID，複製命令到終端並執行。
    以下為新加坡地區的base_url，不同地區需配置對應的 base_url。 
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
  • 當任務處理完成（task_status 為 SUCCEEDED）時，響應中將包含映像URL。映像URL有效期間為24小時，請及時下載。
    由於模型處理時間較長（十幾秒到幾分鐘不等），您可能需要輪詢本介面。建議每隔3-5秒查詢一次，直到 task_status 不為 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":"一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵","actual_prompt":"一間溫馨雅緻的花店，外牆裝飾著精緻的雕花窗戶，窗框為深褐色木質結構，玻璃潔淨透亮，透出店內柔和的光線。花店正門是一扇漂亮的實木門，表面保留天然木紋，配以黃銅門把手和複古門牌，散發出濃厚的手工藝氣息。門前台階兩側和店內窗檯、門口地區錯落有致地擺放著各式鮮花——有盛開的玫瑰、淡雅的繡球、清新的雛菊和翠綠的尤加利葉，色彩豐富而和諧。背景為寧靜的歐洲小鎮街景，石板路與爬滿藤蔓的鄰牆烘托出浪漫氛圍。整體畫面採用寫實攝影風格，光線柔和自然，突出木質紋理與花卉細節。","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":"一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵","actual_prompt":"一間溫馨雅緻的花店，外牆裝飾著一扇精緻的雕花窗戶，窗框為深褐色實木材質，玻璃潔淨透亮，透出店內柔和的光線。花店正門是一扇漂亮的木質門，採用複古做舊工藝，表面保留木紋肌理，配以黃銅門把手和小巧的門牌裝飾，散發出濃厚的手工氣息。門前與店內窗檯、門口兩側錯落有致地擺放著各式鮮花一粉白相間的玫瑰、淡紫色的繡球花、明黃色的向日葵以及翠綠的尤加利葉，色彩柔和而富有層次。背景為一條安靜的歐洲風格小街，石板路與爬滿藤蔓的鄰牆增添浪漫氛圍。整體畫面採用寫實攝影風格，光線溫暖自然，突出花店的寧靜與美好。","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}}%

下一步

成功產生第一張圖片後，您還可進行以下探索：
  • 深入瞭解API參數：查看文生圖API，瞭解更多輸入輸出參數。
  • 體驗視頻產生：調用首幀生視頻API，體驗動態視頻創作。
  • 瀏覽更多模型：訪問百鍊控制台，查看阿里雲百鍊支援的所有映像/視頻模型。
開始使用
Token Plan
模型體驗
  • 音樂產生
接入用戶端/開發工具
模型推理
模型調優
模型部署
模型評測
用量統計與效能監控
資產中心
安全合規
實踐教程
服務支援
產品動態
使用Postman或cURL調用映像/視頻產生API - Alibaba Cloud Model Studio