映像API文檔常見問題 - Alibaba Cloud Model Studio

映像API介面的通用問題匯總，包含介面調試、模型計費與限流、介面高頻報錯等。

本文涉及的映像模型有：文生圖V1和V2、塗鴉作畫、映像局部重繪、Cosplay動漫人物產生、人像風格重繪、虛擬模特、鞋靴模特、映像畫面擴充、人物執行個體分割、映像擦除補全、創意海報產生、映像背景產生、圖配文。

本地調試介面

映像API均支援HTTP調用。下面以文生圖API為例展示本地調試HTTP介面的流程。

需要開通模型服務並擷取API Key，再配置API Key到環境變數（準備下線，併入配置 API Key）。
在映像API文檔中找到curl命令。

樣本：文生圖curl命令

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": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "一間有著精緻窗戶的花店，漂亮的木質門，擺放著花朵"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

若作業系統為macOS或Linux，可在終端執行curl命令。
若作業系統為Windows，可使用Postman、Apifox等介面平台發送HTTP請求。

注意：使用介面平台發送請求時，需要將curl命令Bearer $DASHSCOPE_API_KEY中的$DASHSCOPE_API_KEY替換為真實API_KEY，比如Bearer sk-xxxxxx。

模型計費與限流

模型計費樣本

註：表格中映像模型1、映像模型2僅用作樣本說明，不是真實的模型名稱。

模型名稱	免費額度（查看）	計費單價	限流（主帳號與RAM子帳號共用）
模型名稱	免費額度（查看）	計費單價	任務下發介面QPS限制	同時處理中任務數量
映像模型1	500張	限時免費	2	1
映像模型2	500張	$0.02/張	2	1

免費額度

額度說明：免費額度是指模型成功產生的輸出圖片數量。輸入圖片及模型處理失敗的情況不佔用免費額度。
領取方式：開通阿里雲百鍊大模型服務後自動發放，有效期間90天。
使用帳號：阿里雲主帳號與其RAM子帳號共用免費額度。
更多詳情請參見新人免費額度。

限時免費

當計費為“限時免費”時，表示該模型處於公測階段，免費額度用盡後不可使用。

計費說明

當計費有明確單價時，如$0.02/張，表示該模型已商業化，免費額度用盡或到期後需付費使用。
計費項目：只對模型成功產生的輸出圖片進行收費，其餘情況暫不計費。
付費方式：由阿里雲主帳號統一付費。RAM子帳號不能獨立計量計費，必須由所屬的主帳號付費。如果您需要查詢賬單資訊，請前往阿里雲控制台賬單概覽。
儲值途徑：您可以在阿里雲控制台費用與成本頁面進行儲值。
模型調用情況：您可以前往阿里雲百鍊平台的模型觀測（新加坡或北京）查看模型調用量及調用次數。
更多計費問題請參見計費項目。

限流

限流說明：阿里雲主帳號與其RAM子帳號共用限流限制。

介面報錯

映像無法下載或下載失敗

報錯情境：當使用您自己的圖片連結（非文檔樣本圖片連結）請求介面時，報錯提示“下載圖片失敗，請檢查圖片url”。

{
    "request_id": "657f0d1b-76d0-9e3e-b6d6-xxxxxx",
    "output": {
        "task_id": "5e6fa974-9a25-4271-8659-xxxxxx",
        "task_status": "FAILED",
        "code": "BadRequest.InputDownloadFailed",
        "message": "Reference image download failed, please check image url."
    }
}

可能原因：輸入的圖片URL連結存在錯誤、無法訪問或下載許可權受限等問題，導致模型服務無法成功下載圖片。

解決方案：請確保圖片URL連結完整，並能夠支援公網訪問。您可以將圖片上傳至可供公網訪問的自建儲存服務，或選擇上傳至OSS等雲端儲存體服務。請務必確保圖片URL能夠支援公網訪問。

建立任務介面的curl命令執行失敗

報錯情境：如果您在文檔中複製建立任務介面的curl命令，執行後報錯。下面以映像背景產生模型的curl命令為例。

樣本：映像背景產生-建立任務介面curl命令

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-background-generation-v2",
    "input": {
        "base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
        "ref_image_url": "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/c5e50d27be534709817b2ab080b0162f_0.jpg",
        "ref_prompt": "山脈和晚霞",
        "reference_edge": {
            "foreground_edge": [
                "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png",
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/2c36cc4b7da027279e87311dac48fc2d5d784b1e72c0e-x4f1wC_fw658webp.png"
            ],
            "background_edge": [
                "http://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_edge/0718a9741e07c52ca5506e75c4f2b99e22fff68a4c7d3-P9WGLr_fw658webp.png"
            ],
            "foreground_edge_prompt": [
                "粉色桃花",
                "可愛小狗"
            ],
            "background_edge_prompt": [
                "樹葉"
            ]
        }
    },
    "parameters": {
        "n": 4,
        "ref_prompt_weight": 0.5,
        "model_version": "v3"
    }
}'

報錯資訊顯示“請求Body格式無效”。

{
    "request_id": "d306ae65-3f6d-9d6c-acfb-xxxxxx",
    "code": "InvalidParameter",
    "message": "Required body invalid, please check the request body format."
}

可能原因：建立任務介面的請求Body中存在中文字元。如果執行curl命令的用戶端不支援解析中文，可能會導致請求Body解析異常，從而引發報錯。

解決方案：macOS或者Linux系統使用者直接在終端執行curl命令即可。Windows使用者建議使用HTTP介面平台發送請求，如Postman、Apifox等。

海外調用API介面顯示資源下載逾時

報錯情境：您在海外調用介面，且圖片資源儲存於非中國內地地區，較大機率出現資源下載逾時報錯，報錯資訊如下所示。

Download the media resource timed out during the data inspection process

主要原因：非中國內地地區存在不穩定因素，因此在下載圖片時會導致逾時情況。

解決方案：請將圖片資源儲存在中國內地的地區，並配置加速。注意，當前不支援配置主帳號的圖片下載逾時時間。

其他問題

佈建網域名白名單以訪問圖片OSS連結

映像模型產生的映像儲存於阿里雲OSS，每張映像會被分配一個OSS連結，如https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png。圖片OSS連結允許公開訪問，您可以使用此連結查看或者下載圖片。

如果您的業務對安全性要求較高，您的內網無法訪問阿里雲OSS連結，需要單獨配置外網訪問白名單。請將以下網域名稱添加到白名單中，以便順利訪問圖片連結。

# 圖片OSS網域名稱列表
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com