> ## 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: why the source media URL fails and how to fix it

> When Wan3.0 returns [InvalidParameter] Failed to download, the model service failed to fetch the media URL you passed in — not your key, not a corrupt file. Here is how to tell cross-border congestion, origin rejections, and expired links apart, plus how to host source media reliably.

## Short answer

`[InvalidParameter] Failed to download https://…` means **the model service could not download the media link you passed in**. It is not an APIYI gateway failure, and it is not caused by your key, your parameters, or a corrupt file. The usual cause is that **your origin is too far from mainland China or the path is unstable**, so the fetch does not finish within the download deadline.

## First, the media is not downloaded by us

The API forwards `input.media[].url` to the model service as-is, and the model service fetches the file directly from your origin. So:

* Our gateway logs will not contain a download record for that MP4; finding nothing on our side is expected;
* The fetch requests you see in your origin's nginx come from the model service's fetcher, not from APIYI servers.

## Which of the three causes applies

| Cause | Typical symptom | Quick check |
| - | - | - |
| Cross-border congestion or packet loss | The same file **sometimes succeeds, sometimes fails**; failures take close to 3 minutes | `curl` the URL from a mainland China node and check throughput and loss |
| Origin rejects or is unreachable | Fails fast, within seconds to a minute | Open the link in a private window and check for 200 |
| Link expired or requires auth | Worked before, fails later; or carries signature parameters | Regenerate the link and retry without session cookies |

If the same file (identical SHA-256) has both succeeded and failed, you can assume the first cause.

## Measured reference

We compared the same 1.5 MB reference video at the same time:

| Fetch location | Throughput | Time to pull 1.5 MB |
| - | - | - |
| US node | about 1.4 MB/s | about 1.1 s |
| Mainland China node | 6–11 KB/s | 150–240 s |

The model-side download deadline is on the order of 3 minutes (180 s), so 1.5 MB sits right on the line: slightly better throughput passes, slightly worse fails. That is exactly why the same file is intermittent. Larger files fail far more reliably.

## How to fix it

### 1. Host source media close to mainland China

In order of preference:

1. CDN or object storage in **Hong Kong, Singapore, or Japan** (best cross-border fetch quality, and no ICP filing needed)
2. An international CDN with Asian POPs (Cloudflare, Bunny, CloudFront all work — pick Hong Kong, Singapore, or Tokyo)
3. Direct origin delivery from Europe or the Americas — worst option, and exactly the scenario that fails today

Note: **CDNs in mainland China require an ICP filing for the domain**. Overseas domains such as `.ru` or `.com` usually have none, so mainland nodes are not available; Hong Kong, Singapore, and Japan are the practical choice.

### 2. Reduce the media size

A 10-second 720P reference video is usually only 1–2 MB. If yours is tens of megabytes, lower the bitrate or resolution. Based on the measurements above, anything above 3 MB rarely finishes in time.

### 3. Check the link itself

* Publicly reachable without a session, cookies, or a Referer allowlist;
* Returns 200 with a complete `Content-Length` and supports `Range`;
* Avoid short-lived signed URLs, or make sure they outlive the task.

### 4. Retrying does not help

Retrying only buys another 3-minute wait. Throughput has not changed, so the success rate matches the first attempt.

## When to contact support

If your media already sits on a Hong Kong, Singapore, or Japan node and is under 3 MB but still fails consistently, send us:

* The task ID (`task_id`)
* The full media URL
* When the failure happened (with time zone)

We will retest the path from a mainland China node and escalate it to the model provider.


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