> ## 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.