如何使用postman或curl調用HTTP請求？ - Alibaba Cloud Model Studio

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

Postman：一款介面化的 HTTP 測試載入器，操作直觀，推薦初學者使用。
cURL：一個強大的命令列工具，適用於熟悉命令列的開發人員。

說明

Postman 和 cURL僅適用於快速測試與功能驗證。對於生產環境，建議您使用官方 SDK 或自行實現 HTTP 調用。

API非同步呼叫機制

由於映像與視頻產生任務耗時較長（十幾秒到數分鐘不等），為避免長時間的HTTP串連等待和逾時，API採用非同步呼叫機制。整個調用過程分為兩步：

建立任務：調用 API 建立任務，服務會同步返回一個任務 ID（task_id）。
查詢結果：使用該 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替換為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": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

在 Postman 中，單擊new或+ 按鈕建立一個新請求，請求類型選擇HTTP。
在要求方法下拉式功能表中選擇POST，並根據您的模型所在地區填入對應的 URL：
- 國際（新加坡）地區：https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
- 中國大陸（北京）地區：https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

點擊Headers標籤頁，添加以下三個索引值對。

Key	Value	說明
X-DashScope-Async	enable	啟用非同步呼叫
Authorization	Bearer sk-xxx（請將sk-xxx替換為阿里雲百鍊API Key）	身分識別驗證憑證
Content-Type	application/json	聲明請求體為JSON格式

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

步驟2：根據task_id查詢結果

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

以下為國際（新加坡）地區base_url，若使用中國大陸（北京）地區的模型，需將base_url替換為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"

在 Postman 中配置查詢請求：
1. 建立一個HTTP請求。
2. 配置要求方法為GET 。
3. 根據地區，填入查詢URL，將URL中的 {task_id} 替換為在步驟1中擷取的真實 task_id。
4. 在Headers標籤頁中，添加 Authorization 鍵，其值與步驟1中使用的 API Key 相同。
5. 點擊Send發送請求。
檢查返回結果。重複發送此請求（輪詢），直到 task_status 變為 SUCCEEDED，擷取映像的URL。映像URL有效期間為24小時，請及時下載。

方式二：使用cURL發送請求

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

前提條件

在執行cURL命令之前，您需要：

已開通模型服務並擷取API Key。
確保您的系統中已安裝 cURL，並配置API Key到環境變數（準備下線，併入配置 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替換為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": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

成功請求後將返回task_id。有效期間 24 小時，到期後無法查詢。請及時擷取結果。

步驟2：根據task_id查詢結果

將以下命令中的 {task_id} 替換為步驟 1 中擷取的任務 ID，複製命令到終端並執行。
以下為國際（新加坡）地區base_url，若使用中國大陸（北京）地區的模型，需將base_url替換為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"
```
當任務處理完成（task_status 為 SUCCEEDED）時，響應中將包含映像URL。映像URL有效期間為24小時，請及時下載。
由於模型處理時間較長（十幾秒到幾分鐘不等），您可能需要輪詢本介面。建議每隔3-5秒查詢一次，直到 task_status 不為 RUNNING。

下一步

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

深入瞭解API參數：查看文生圖API，瞭解更多輸入輸出參數。
體驗視頻產生：調用首幀生視頻API，體驗動態視頻創作。
瀏覽更多模型：訪問模型列表，查看阿里雲百鍊支援的所有映像/視頻模型。