> ## 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: ошибка загрузки — почему URL исходного медиад файла не работает и как это исправить

> Когда Wan3.0 возвращает [InvalidParameter] Failed to download, сервис модели не смог получить медиаданные по переданному вами URL — проблема не в вашем ключе и не в повреждённом файле. Здесь описано, как отличить перегрузку трансграничного соединения от отклонения запроса исходным сервером и истёкшей ссылки, а также как надёжно размещать исходные медиаданные.

## Краткий ответ

`[InvalidParameter] Failed to download https://…` означает, что **сервис модели не смог загрузить медиафайл по переданной вами ссылке**. Это не сбой шлюза APIYI и не связано с вашим ключом, параметрами или повреждённым файлом. Обычно причина в том, что **ваш источник находится слишком далеко от материкового Китая или соединение нестабильно**, поэтому загрузка не завершается до истечения отведённого времени.

## Во-первых, мы не загружаем медиафайл

API передаёт `input.media[].url` в сервис модели как есть, а сервис модели напрямую загружает файл из вашего источника. Поэтому:

* В журналах нашего шлюза не будет записи о загрузке этого MP4; отсутствие такой записи с нашей стороны — ожидаемое поведение;
* Запросы на загрузку, которые вы видите в nginx вашего источника, поступают от загрузчика сервиса модели, а не от серверов APIYI.

## Какая из трёх причин применима

| Причина | Типичный симптом | Быстрая проверка |
| - | - | - |
| Перегрузка или потеря пакетов при трансграничной передаче | Один и тот же файл **то загружается успешно, то завершается ошибкой**; сбои происходят примерно через 3 минуты | `curl` URL с узла в материковом Китае и проверьте пропускную способность и потери |
| Источник отклоняет запрос или недоступен | Сбой происходит быстро — от нескольких секунд до минуты | Откройте ссылку в приватном окне и проверьте наличие ответа 200 |
| Срок действия ссылки истёк или требуется авторизация | Ранее ссылка работала, но позже перестала; либо содержит параметры подписи | Сгенерируйте ссылку заново и повторите попытку без cookies сеанса |

Если один и тот же файл (с идентичным SHA-256) и загружался успешно, и завершался ошибкой, можно предположить, что применима первая причина.

## Измерения

Мы одновременно загрузили один и тот же эталонный видеофайл размером 1,5 МБ:

| Место загрузки | Пропускная способность | Время загрузки 1,5 МБ |
| - | - | - |
| Узел в США | около 1,4 МБ/с | около 1,1 с |
| Узел в материковом Китае | 6–11 КБ/с | 150–240 с |

Срок загрузки на стороне модели составляет примерно 3 минуты (180 с), поэтому файл размером 1,5 МБ оказывается на границе: при немного более высокой пропускной способности загрузка проходит, при немного более низкой — завершается с ошибкой. Именно поэтому один и тот же файл то загружается, то нет. Файлы большего размера с гораздо большей вероятностью не загружаются.

## Как это исправить

### 1. Разместите исходные медиафайлы ближе к материковому Китаю

В порядке предпочтения:

1. CDN или объектное хранилище в **Гонконге, Сингапуре или Японии** (лучшее качество трансграничной загрузки, регистрация ICP не требуется)
2. Международный CDN с POP-узлами в Азии (подойдут Cloudflare, Bunny и CloudFront — выберите Гонконг, Сингапур или Токио)
3. Прямая доставка с исходного сервера из Европы или Америки — худший вариант, именно в этом сценарии возникает текущая проблема

Примечание: **для CDN в материковом Китае требуется регистрация ICP домена**. У зарубежных доменов, таких как `.ru` или `.com`, обычно такой регистрации нет, поэтому узлы в материковом Китае недоступны; на практике подходят Гонконг, Сингапур и Япония.

### 2. Уменьшите размер медиафайла

Эталонное видео длительностью 10 секунд в разрешении 720P обычно занимает всего 1–2 МБ. Если ваш файл весит десятки мегабайт, снизьте битрейт или разрешение. Судя по приведённым выше измерениям, загрузка файлов размером более 3 МБ редко успевает завершиться вовремя.

### 3. Проверьте саму ссылку

* Доступна публично, без сессии, cookies или списка разрешённых Referer;
* Возвращает ответ 200 с полным `Content-Length` и поддерживает `Range`;
* Не используйте краткосрочные подписанные URL либо убедитесь, что срок их действия превышает время выполнения задачи.

### 4. Повторные попытки не помогут

Повторная попытка лишь добавит ещё 3 минуты ожидания. Скорость передачи данных не изменилась, поэтому вероятность успеха останется такой же, как при первой попытке.

## Когда обращаться в службу поддержки

Если ваш медиафайл уже находится на узле в Гонконге, Сингапуре или Японии, его размер не превышает 3 МБ, но запрос по-прежнему стабильно завершается ошибкой, отправьте нам:

* ID задачи (`task_id`)
* Полный URL медиафайла
* Время возникновения ошибки (с указанием часового пояса)

Мы повторно проверим маршрут с узла в материковом Китае и передадим проблему поставщику модели.


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