# Wan 3.0 Prime (https://wanapi.app/ko/docs/wan-3-0-prime) Wan 3.0 Prime은 별도의 모델 ID와 요금을 사용하며, 해상도는 일반 모델과 동일하게 480p, 720p, 1080p를 지원합니다. 텍스트, 이미지, 참조 미디어를 입력할 수 있습니다. [모델 상세 정보 및 플레이그라운드](/ko/models/wan-3-0-prime). ## Wan API 연결 [#wan-api-연결] API 기본 URL은 `https://api.wanapi.app`입니다. [API 키 설정](/ko/settings/apikeys)에서 키를 생성한 뒤 `Authorization: Bearer YOUR_API_KEY`로 전송하세요. 키는 서버에 보관하세요. 플레이그라운드는 웹사이트 세션으로 인증하며 같은 계정 잔액에서 비용을 차감합니다. 브라우저에 키를 붙여 넣을 필요가 없습니다. API를 사용하려면 계정이 활성화되어 있고 잔액이 충분해야 합니다. 현재 요금은 [요금 페이지](/ko/pricing)에서 확인하세요. 각 모델에는 전용 엔드포인트와 [모델 페이지](/ko/models)가 있습니다. `GET /v1/models`는 해당 키로 사용할 수 있는 모델 목록을 반환합니다. 더 높은 해상도를 선택해도 모델이 자동으로 변경되지는 않습니다. | 설정 | Wan 3.0 Prime | | ------------ | ----------------------------------------------------------------- | | 모델 ID | `wan3.0-video-prime` | | `resolution` | `480p`, `720p`, `1080p`. 기본값: `1080p`. | | `duration` | 출력 길이 2–30초. 자동 길이는 `-1`. 기본값: `5`. | | `ratio` | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. 기본값: `adaptive`. | | `audio` | 기본값: `true`. `false`로 설정해도 요금은 낮아지지 않습니다. | [공통 요청 필드](#요청-필드)에서 네이티브 필드 14개 전체와 미디어 제한, 입력 조합을 확인할 수 있습니다. 이 모델은 네이티브 요청의 URL과 [Responses 요청](#동기-및-백그라운드-responses)의 `model` 값에 `wan3.0-video-prime`를 사용합니다. ## Wan 3.0 Prime 작업 제출 [#wan-30-prime-작업-제출] 이 예시는 해당 모델의 가장 낮은 해상도로 2초 길이의 텍스트 기반 동영상 생성을 요청합니다. 서버에서 `WAN_API_KEY`를 자신의 키로 설정하세요. URL로 모델을 선택하므로 이 네이티브 JSON 본문에 `model` 필드를 추가하지 마세요. ```bash curl https://api.wanapi.app/wan/v1/wan3.0-video-prime/generation \ -H "Authorization: Bearer $WAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A blue glass bottle turns slowly on a white pedestal. Static camera.", "duration": 2, "resolution": "480p", "ratio": "16:9", "audio": false, "prompt_extend": false }' ``` ## Wan 3.0 Prime 작업 조회 [#wan-30-prime-작업-조회] 반환된 `task_info.id`를 `TASK_ID`로 저장한 뒤 동일한 모델 엔드포인트로 조회하세요. 제출 응답은 완료된 동영상이 아니라 작업 접수 결과입니다. 5초 간격으로 상태 조회를 시작하세요. [작업 상태 및 다운로드](#작업-상태-조회-및-동영상-다운로드)에서 자세한 내용을 확인할 수 있습니다. ```bash curl "https://api.wanapi.app/wan/v1/wan3.0-video-prime/generation/$TASK_ID" \ -H "Authorization: Bearer $WAN_API_KEY" ``` ## Wan 3.0 Prime 요금 [#wan-30-prime-요금] 표에는 현재 적용되는 과금 대상 1초당 USD 요금이 표시됩니다. 참조 동영상 입력 길이와 생성된 출력 길이가 모두 포함됩니다. 5초 예시는 참조 동영상이 없는 경우를 기준으로 합니다. 비용 예약과 정산에 대해서는 [과금 및 오류 처리](#과금-및-오류-처리)를 참조하세요. [Wan 3.0 Prime 요금 보기](/ko/models/wan-3-0-prime#pricing). ## 요청 필드 [#요청-필드] 네 모델 모두 아래의 네이티브 필드 14개를 사용합니다. 프롬프트 또는 하나 이상의 미디어 입력을 제공하세요. 프레임 입력은 참조 입력, `file`, `link`와 함께 사용할 수 없습니다. `file`과 `link`도 동시에 사용할 수 없습니다. | 필드 | 자료형 | 규칙 | | ------------------ | --------- | ----------------------------------------------------------------- | | `prompt` | string | 최대 20,000자. | | `first_frame` | string | 이미지 HTTP(S) URL, 이미지 data URI 또는 Base64. | | `last_frame` | string | 이미지 HTTP(S) URL, 이미지 data URI 또는 Base64. | | `reference_images` | string\[] | 최대 10개 이미지. 프레임과 같은 입력 형식을 사용합니다. | | `reference_videos` | string\[] | 공개 MP4/MOV URL 최대 5개. 클립당 1–15초이며, 참조 동영상의 총길이는 15초 이하여야 합니다. | | `reference_audios` | string\[] | 오디오 HTTP(S) URL 최대 5개. | | `file` | string | 공개 문서 URL. | | `link` | string | 공개 웹페이지 URL. | | `resolution` | string | 위 모델 표를 참조하세요. 기본값: `1080p`. | | `ratio` | string | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. 기본값: `adaptive`. | | `duration` | integer | 출력 길이 2–30초. 자동 길이는 `-1`. 기본값: `5`. | | `audio` | boolean | 오디오 생성 여부. 기본값: `true`. 끄더라도 요금은 낮아지지 않습니다. | | `seed` | integer | 0–2147483647. 생략하면 무작위로 생성합니다. | | `prompt_extend` | boolean | 프롬프트 확장 여부. 기본값: `true`. | 작업이 끝날 때까지 직접 접근할 수 있는 안정적인 미디어 URL을 사용하세요. 동영상 길이는 제한된 범위의 HTTP Range 요청으로 확인합니다. 동영상 서버는 이러한 요청을 지원하고 읽을 수 있는 MP4/MOV 길이 메타데이터를 제공해야 합니다. 길이 확인 시 리디렉션은 따라가지 않습니다. 사설 네트워크 URL은 지원하지 않습니다. 참조 동영상과 출력 동영상의 합산 길이는 30초를 넘을 수 없습니다. 플레이그라운드는 최대 32 MiB의 JSON 요청 본문을 허용합니다. 더 큰 입력에는 URL을 사용하세요. ## 작업 상태 조회 및 동영상 다운로드 [#작업-상태-조회-및-동영상-다운로드] 모든 모델의 제출 엔드포인트는 외부 API에서 사용할 작업 ID를 반환합니다. 다른 처리를 하기 전에 먼저 이 ID를 저장하세요. ```json { "task_info": { "id": "task_EXAMPLE", "status": "pending" } } ``` 해당 모델 절의 조회 예시를 사용하세요. 5초 간격으로 시작하고 일시적인 오류가 발생하면 대기 시간을 늘리세요. 각 작업의 모델 ID와 작업 ID를 함께 보관하고, 다른 모델 엔드포인트로 조회하지 마세요. 네이티브 상태 값은 `pending`, `processing`, `completed`, `failed`입니다. 완료된 응답에는 완전한 Bunny CDN 서명 URL을 담은 `videos` 배열이 포함됩니다. ```json { "task_info": { "id": "task_EXAMPLE", "status": "completed" }, "videos": ["https://reapiflexible.b-cdn.net/flexible/v1/expires/2026-11/20261113T06/wanapi-task_EXAMPLE/video.mp4?token=HS256_SIGNATURE&expires=1794550071"] } ``` 반환된 URL을 재생이나 다운로드에 바로 사용할 수 있습니다. 이 URL에는 API 키나 Authorization 헤더가 필요하지 않습니다. 파일에는 저장소의 기존 보관 정책이 적용됩니다. 작업을 다시 조회해도 동영상이 다시 생성되거나 추가 요금이 부과되지 않으며 파일의 보관 기한도 연장되지 않습니다. 계속 보관할 파일은 자신의 저장소에 저장하세요. 작업 조회에는 API 키가 필요하며 해당 계정이 소유한 작업만 반환됩니다. ## 동기 및 백그라운드 Responses [#동기-및-백그라운드-responses] Responses API를 사용하는 클라이언트는 `POST /v1/responses`에 모델 ID, 문자열 `input`, 동일한 네이티브 생성 필드를 전달할 수 있습니다. `prompt` 대신 `input`을 사용하세요. `reference_images`와 같은 네이티브 미디어 필드는 최상위 필드로 전달합니다. ```json { "model": "wan3.0-video-prime", "input": "A blue ball rolls across a white table.", "resolution": "480p", "duration": 2, "background": true } ``` `background: true`를 사용하면 응답 ID를 저장한 뒤 `GET /v1/responses/{response_id}`를 주기적으로 조회하세요. `background`가 없으면 HTTP 요청은 생성이 완료될 때까지 대기합니다. `stream: true`는 대기 중에 서버 전송 이벤트(SSE)를 사용합니다. 최종 assistant 출력에는 서명된 동영상 URL이 포함됩니다. 이 URL 자체가 접근 권한을 부여하므로 비공개로 보관하고 실수로 공개하지 마세요. 생성 시간이 길거나 프록시의 요청 제한 시간이 짧다면 네이티브 작업 제출 또는 백그라운드 Responses를 권장합니다. 동기 요청의 연결이 끊기거나 제한 시간을 초과해도 생성은 취소되지 않습니다. 작업은 서버에 남습니다. 같은 생성 요청을 자동으로 다시 제출하지 마세요. ## 과금 및 오류 처리 [#과금-및-오류-처리] 비용은 해당 모델의 해상도별 초당 요금에 과금 대상 초를 곱해 계산합니다. 참조 동영상과 출력 동영상의 길이가 모두 포함됩니다. 텍스트, 이미지, 오디오 입력은 동영상 과금 초를 추가하지 않습니다. 참조 동영상이 없는 고정 길이 요청은 요청한 출력 길이에 해당하는 비용을 예약합니다. 자동 길이 및 참조 동영상 요청은 과금 대상 최대 30초에 해당하는 비용을 예약한 뒤 실제 측정 사용량으로 정산하고 사용하지 않은 예약 금액을 반환합니다. 생성에 실패하면 예약 금액이 해제됩니다. 상태 조회는 새 생성 작업을 만들거나 비용을 다시 청구하지 않습니다. * **잘못된 매개변수:** 요청을 수정한 뒤 다시 제출하세요. 알 수 없는 네이티브 필드는 거부됩니다. * **잔액 부족:** 새로운 유료 요청을 제출하기 전에 잔액을 충전하세요. 키의 사용 한도는 계정 잔액을 제공하지 않습니다. * **요청 제한 또는 일시적인 상태 조회 실패:** 조회만 재시도하되 대기 시간을 늘리고 최대 대기 시간을 정하세요. * **제출 시간 초과, 네트워크 중단 또는 작업 ID 누락:** 제출 결과가 불확실할 수 있습니다. 두 번째 유료 작업이 생성될 수 있으므로 POST 요청을 자동으로 반복하지 마세요. * **작업 실패:** 작업 실패 상태와 상태 조회 불가를 구분해 표시하세요. * **다운로드 실패:** 새 생성을 시작하기 전에 이미 완료된 작업의 다운로드를 재시도하세요. 생성 요청은 자동으로 재시도되거나 다른 모델로 전환되지 않습니다. 취소, 웹훅, 멱등성 키에 대한 API 규약은 제공하지 않습니다. 제출 결과가 불확실해 확인이 필요하면 작업 ID를 보관하고 [지원팀](/ko/contact)에 문의하세요.