> ## 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을 가져오지 못한 것입니다. API 키 문제도 아니고 파일 손상도 아닙니다. 국경 간 네트워크 혼잡, 원본 서버의 요청 거부, 만료된 링크를 구분하는 방법과 소스 미디어를 안정적으로 호스팅하는 방법을 설명합니다.

## 짧은 답변

`[InvalidParameter] Failed to download https://…`는 **모델 서비스가 전달하신 미디어 링크를 다운로드하지 못했다는 의미입니다**. APIYI 게이트웨이 장애가 아니며, 키나 매개변수 또는 파일 손상으로 발생한 문제도 아닙니다. 일반적인 원인은 **원본 서버가 중국 본토에서 너무 멀리 있거나 연결 경로가 불안정하여**, 다운로드 제한 시간 내에 가져오기가 완료되지 않는 것입니다.

## 먼저 미디어는 저희가 다운로드하지 않습니다

API는 `input.media[].url`을(를) 있는 그대로 모델 서비스로 전달하며, 모델 서비스가 사용자의 오리진에서 직접 파일을 가져옵니다. 따라서 다음과 같습니다.

* 저희 게이트웨이 로그에는 해당 MP4의 다운로드 기록이 남지 않습니다. 저희 측에서 아무 기록도 찾을 수 없는 것은 정상입니다.
* 사용자의 오리진 nginx에서 확인되는 가져오기 요청은 APIYI 서버가 아니라 모델 서비스의 가져오기 도구에서 발생합니다.

## 세 가지 원인 중 해당하는 항목

| 원인 | 일반적인 증상 | 빠른 확인 방법 |
| - | - | - |
| 국경 간 혼잡 또는 패킷 손실 | 같은 파일이 **성공할 때도 있고 실패할 때도 있음**; 실패까지 거의 3분이 걸림 | `curl` 중국 본토 노드에서 URL을 확인하고 처리량과 손실률을 점검합니다 |
| 원본 서버가 요청을 거부하거나 연결할 수 없음 | 몇 초에서 1분 이내에 빠르게 실패함 | 비공개 창에서 링크를 열고 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이나 오브젝트 스토리지(국경 간 가져오기 품질이 가장 좋고 ICP 등록이 필요하지 않습니다)
2. 아시아 POP를 보유한 국제 CDN(Cloudflare, Bunny, CloudFront 모두 사용할 수 있습니다. 홍콩, 싱가포르 또는 도쿄를 선택하십시오)
3. 유럽이나 아메리카에서 직접 원본을 전송하는 방식(가장 좋지 않은 선택이며, 현재 실패하는 바로 그 시나리오입니다)

참고: **중국 본토의 CDN을 사용하려면 도메인에 ICP 등록이 필요합니다**. `.ru` 또는 `.com` 같은 해외 도메인은 대개 등록되어 있지 않으므로 중국 본토 노드를 사용할 수 없습니다. 실용적인 선택지는 홍콩, 싱가포르, 일본입니다.

### 2. 미디어 크기를 줄입니다

10초 분량의 720P 참조 동영상은 보통 1\~2MB에 불과합니다. 파일 크기가 수십 메가바이트라면 비트레이트나 해상도를 낮추십시오. 위 측정 결과에 따르면 3MB를 초과하는 파일은 제한 시간 내에 전송을 완료하는 경우가 드뭅니다.

### 3. 링크 자체를 확인합니다

* 세션, 쿠키 또는 Referer 허용 목록 없이 공개적으로 접근할 수 있어야 합니다.
* 완전한 `Content-Length`와 함께 200을 반환하고 `Range`를 지원해야 합니다.
* 만료 시간이 짧은 서명 URL은 피하거나, 작업이 끝날 때까지 유효하도록 설정하십시오.

### 4. 재시도해도 도움이 되지 않습니다

재시도하면 3분을 더 기다릴 뿐입니다. 처리량은 달라지지 않으므로 성공률은 첫 번째 시도와 같습니다.

## 지원팀에 문의해야 하는 경우

미디어가 이미 홍콩, 싱가포르 또는 일본 노드에 있고 3MB 미만인데도 계속 일관되게 실패하는 경우 다음 정보를 보내 주십시오.

* 작업 ID(`task_id`)
* 전체 미디어 URL
* 실패가 발생한 시점(시간대 포함)

중국 본토 노드에서 경로를 다시 테스트한 후 모델 제공업체에 에스컬레이션하겠습니다.


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