> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan3.0 報 Failed to download：素材連結打不開怎麼解決

> Wan3.0 影片生成返回 [InvalidParameter] Failed to download 時，是模型側拉取你傳入的素材 URL 失敗，不是金鑰或檔案損壞。本文給出跨洲鏈路、源站拒絕、連結過期三類成因的判別方法與穩定分發方案。

## 簡短回答

`[InvalidParameter] Failed to download https://…` 表示**模型服務去下載你傳入的素材連結時失敗了**：不是 API易 閘道下載失敗，也不是你的 Key、引數或檔案損壞。最常見的原因是**源站離中國大陸太遠、鏈路抖動**，在下載時限內沒把檔案拉完。

## 先確認：素材不是我們下載的

介面只把請求裡的 `input.media[].url` 原樣轉給模型服務，素材由模型側直接回源拉取。所以：

* 我們的閘道日誌裡不會有這個 MP4 的下載記錄，在我們這邊查「下載失敗」查不到東西是正常的；
* 你在源站 nginx 裡看到的抓取請求，來自模型服務的抓取器，不是 API易 的伺服器。

## 三類成因怎麼分

| 成因 | 典型表現 | 快速驗證 |
| - | - | - |
| 跨洲鏈路慢或丟包 | 同一個檔案**有時成功、有時失敗**；失敗耗時接近 3 分鐘 | 從中國大陸節點 `curl` 該 URL，看速率與丟包 |
| 源站拒絕或不可達 | 很快失敗，幾秒到一分鐘內就返回 | 無痕視窗直接開啟連結，看是否 200 |
| 連結過期或需鑑權 | 之前能用、後來失效；或帶簽名引數 | 重新生成連結，去掉登入態再試 |

如果同一個檔案（SHA-256 相同）既成功過也失敗過，基本可以直接鎖定第一類。

## 實測參考

我們用一個 1.5 MB 的參考影片做過對比（同一檔案、同一時段）：

| 拉取位置 | 速率 | 拉完 1.5 MB 需要 |
| - | - | - |
| 美國節點 | 約 1.4 MB/s | 約 1.1 秒 |
| 中國大陸節點 | 6–11 KB/s | 150–240 秒 |

模型側的下載時限在 3 分鐘（180 秒）量級，所以 1.5 MB 剛好卡在線上——速率稍好就過，稍差就失敗，這就是「時好時壞」的來源。檔案越大越必然失敗。

## 怎麼解決

### 1. 把素材放到離中國大陸近的節點

優先順序：

1. **香港 / 新加坡 / 日本**的 CDN 或物件儲存（跨境回源品質最好，也不需要備案）
2. 有亞洲節點的國際 CDN（Cloudflare、Bunny、CloudFront 等都可以，注意選香港 / 新加坡 / 東京）
3. 源站直出（歐洲、美洲）——最差，也正是當前出問題的場景

注意：**中國大陸的 CDN 需要域名完成 ICP 備案**，`.ru`、`.com` 這類境外域名通常沒有備案，用不了大陸節點，所以香港 / 新加坡 / 日本是更現實的選擇。

### 2. 壓縮素材體積

10 秒 720P 的參考影片通常只有 1–2 MB；如果動輒十幾 MB，建議降位元速率或降解析度。按上面的實測，超過 3 MB 基本很難在時限內拉完。

### 3. 檢查連結本身

* 公網可直接訪問，不需要登入態、Cookie、Referer 白名單；
* 返回 200 且 `Content-Length` 完整，支援 `Range`；
* 不要用會過期的臨時簽名連結（或者保證在任務跑完前不過期）。

### 4. 不要靠重試解決

重試只會多等幾個 3 分鐘。鏈路速率不變，重試的成功率和第一次一樣。

## 什麼時候聯絡客服

如果素材已經放到香港 / 新加坡 / 日本節點、體積也壓到 3 MB 以內，仍然穩定報這個錯，把下面三樣發給我們：

* 任務 ID（`task_id`）
* 素材完整 URL
* 失敗發生的時間（帶時區）

我們會從國內節點複測這條鏈路，並同步給模型服務方排查。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.