Alibaba Cloud Model Studio：常見問題

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

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

本地調試介面

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

1. 需要開通模型服務並擷取API Key，再配置API Key到環境變數。
2. 在映像API文檔中找到curl命令。

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

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

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

模型計費與限流

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

• 額度說明：免費額度是指模型成功產生的輸出圖片數量。輸入圖片及模型處理失敗的情況不佔用免費額度。
• 領取方式：開通阿里雲百鍊大模型服務後自動發放，有效期間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能夠支援公網訪問。

調用圖片產生 API 返回 InvalidParameter: url error

報錯情境：調用圖片產生 API (/api/v1/services/aigc/text2image/image-synthesis) 時，model 參數填寫了文本產生模型名（如 qwen-turbo），介面返回如下報錯。

{
    "code": "InvalidParameter",
    "message": "url error, please check url！"
}

使用 OpenAI 相容模式並填寫文本產生模型名時，介面返回空響應。

可能原因：model 參數與調用的介面不匹配。圖片產生介面只接受圖片產生模型名，傳入文本產生模型名（如 qwen-turbo）時，服務端無法正確解析請求，從而返回 url error。報錯文案中的“url”並不代表請求地址或圖片連結有問題。

解決方案：將 model 參數改為圖片產生模型名（如 wanx2.1-t2i-turbo），並按非同步方式調用。

curl -X POST https://{WorkspaceId}.cn-beijing.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": "wanx2.1-t2i-turbo",
    "input": {
        "prompt": "a cute cat"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}'

圖片產生 API 為非同步呼叫，建立任務成功後返回 task_id，需通過 GET /api/v1/tasks/{task_id} 輪詢任務結果，task_status 變為 SUCCEEDED 後即可擷取產生的圖片 URL。

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

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.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

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

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

文生圖產生的文字異常怎麼辦

問題情境：當您在Prompt中包含文字描述（如"海報上寫著某某文字"）時，早期萬相文生圖模型（如wanx-v1、wanx2.0、wanx2.1系列）產生的圖片中文字可能出現變形、亂碼或無法正常顯示的情況。

問題原因：早期萬相文生圖模型對文字渲染能力有限，在產生圖片時無法準確渲染Prompt中指定的文字內容，這是模型能力的限制而非介面Bug。

解決方案：

1. 推薦方案：使用支援文字渲染的模型。千問映像產生模型（如qwen-image-2.0-pro、qwen-image-plus）具備專業的文字渲染能力，能夠準確產生Prompt中指定的文字內容。此外，萬相2.5及以上版本（如Wan2.5-T2I-Preview）也支援中英文及小語種文字產生。
2. 如果必須使用早期萬相模型，建議先產生不含文字的圖片，再使用圖片編輯軟體手動添加所需的文字內容。