幫助中心
首頁 Alibaba Cloud Model Studio 操作指南（模型） 接入用戶端/開發工具 Postman

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

更新時間：
Copy as MD
產品

本文介紹使用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參數

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://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

    • 華北2（北京）：https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

    各地區支援的模型請參見百鍊控制台，當前地區與服務部署範圍為系統預設綁定關係，不支援自由組合。

    1-intl

  3. 點擊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格式

  4. 配置請求體 (Body)

    • 點擊 Body 標籤頁，選中 raw 單選框，然後在右側的格式下拉式功能表中選擇JSON，將cURL樣本中的 -d 後面的 JSON 內容粘貼到輸入框。

      {
    "model": "wan2.5-t2i-preview",
    "input": {
        "prompt": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

    • （可選）點擊頁面右側的 Beautify，可以格式化JSON格式，使其更易閱讀。

    3-intl-zh

  5. 點擊Send發送請求，並擷取 task_id。有效期間 24 小時，到期後無法查詢，請及時擷取結果。

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

    4-

步驟2：根據task_id查詢結果

擷取到 task_id 後，需要通過查詢介面來擷取最終結果。

  • 新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis，請將WorkspaceId替換為真實的擷取Workspace ID

  • 美國（維吉尼亞）：https://dashscope-us.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發送請求。

    5-zh

  2. 檢查返回結果。重複發送此請求（輪詢），直到 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 是否已安裝。

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

    task_id-intl-zh

步驟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=xxx"}],"task_metrics":{"TOTAL":1,"FAILED":0,"SUCCEEDED":1}},"usage":{"image_count":1}}

    result-intl-zh

下一步

成功產生第一張圖片後，您還可進行以下探索：

  • 深入瞭解API參數：查看文生圖API，瞭解更多輸入輸出參數。

  • 體驗視頻產生：調用首幀生視頻API，體驗動態視頻創作。

  • 瀏覽更多模型：訪問百鍊控制台，查看阿里雲百鍊支援的所有映像/視頻模型。

上一篇：Kilo CLI下一篇：Dify