Wan 3.0 Video Prime API
wan3.0-video-prime의 전체 APIMaster 요청 매개변수, 라우트 차이점, 미디어 제약, 비동기 폴링, 다운로드 및 청구.
Wan 3.0 Video Prime API
APIMaster 비동기 비디오 API를 통해 wan3.0-video-prime을 사용하십시오. 현재 통합은 480P / 720P / 1080P, 2–30 정수 초, 작업당 비디오 1개를 제공합니다. 매개변수 및 통합 검토: 2026-10-26.
엔드포인트 및 인증
| 작업 | 메서드 및 URL |
|---|---|
| 생성 | POST https://apimaster.ai/v1/videos |
| 조회 | GET https://apimaster.ai/v1/videos/{task_id} |
| 다운로드 | GET https://apimaster.ai/v1/videos/{task_id}/content |
모든 요청에서 Authorization: Bearer YOUR_API_KEY를 사용하고 작업을 생성할 때는 Content-Type: application/json을 사용하십시오. Alibaba Cloud 키가 아닌 APIMaster API 키를 사용하십시오. APIMaster가 업스트림 비동기 헤더를 제공하므로 X-DashScope-Async는 필요하지 않습니다.
호환 생성 엔드포인트 /videos/generations는 다른 응답 봉투를 반환합니다. 아래 예제는 일관되게 /videos를 사용합니다.
현재 라우트 기능
현재 이 모델을 제공하는 두 가지 통합은 Alibaba Cloud 네이티브 라우트와 GMI 라우트입니다. 고급 필드는 해당 라우트가 필요합니다. 필드를 제출한다고 해서 해당 라우트가 선택되지는 않습니다. 라우트별 예제를 사용하기 전에 API 키가 어떤 라우트에 액세스할 수 있는지 확인하십시오.
| 기능 | Alibaba Cloud 네이티브 | GMI |
|---|---|---|
| 텍스트-투-비디오, 첫 프레임, 첫/마지막 프레임, 참조 이미지 | 통합됨 | 통합됨, 미디어 필드가 다름 |
| 참조 오디오 | metadata.input.media |
audio_url |
| 문서 / 공개 웹 페이지 | 네이티브 미디어 필드는 전달됩니다; 완료된 생성 검사에서는 다루지 않습니다 | 지원되지 않음 |
| 참조 비디오, 편집, 확장 | 제출 전에 차단됨 | 지원되지 않음 |
자동 길이 -1 |
차단됨 | 차단됨 |
화면 비율 21:9 |
허용됨 | 거부됨 |
| 명시적 오디오 스위치 | generate_audio / audio |
지원되지 않음; 이 필드를 생략하십시오 |
프롬프트 재작성 비활성화 / 고정 시드 0 |
현재 직렬화는 prompt_extend: false 또는 seed: 0을 보존하지 않습니다; 이에 의존하지 마십시오 |
명시적 false와 0은 보존됩니다 |
네이티브 라우트의 5초 720P 무음 비디오는 2026-10-24 승인 검사에서 완료, 다운로드 및 디코딩에 성공했습니다. 다른 미디어 조합은 생성 테스트된 조합으로 제시된 것이 아니라 어댑터와 공식 계약에서 설명된 것입니다. 라우트 가용성과 가격은 변경될 수 있습니다; 모델 카드를 참조하십시오.
전체 공통 요청 매개변수
이 필드를 최상위에 보내십시오. 가장 넓은 호환성을 위해 명시적 duration, resolution, aspect_ratio를 사용하고, 최대 5,000자의 비어 있지 않은 프롬프트를 사용하며, 라우트별 옵션은 생략하십시오.
| 필드 | 유형 | 필수 / 기본값 | APIMaster 동작 |
|---|---|---|---|
model |
문자열 | 필수 | 정확히 wan3.0-video-prime |
prompt |
문자열 | 두 라우트 모두에서 필수 | 비어 있지 않아야 하며 이미지 생성에서도 마찬가지입니다. GMI는 1–5,000자를 검증합니다; 네이티브 어댑터는 비어 있지 않은 텍스트를 요구합니다. 공식 네이티브 한도는 20,000자입니다; 라우트 전반에서 그 더 높은 한도에 의존하지 마십시오 |
duration |
정수 | 5 |
2–30초; -1, 소수 또는 자동 길이는 허용되지 않습니다 |
seconds |
문자열 | 선택 사항 | 문자열 별칭(예: "5"); 둘 다 제공된 경우 duration과 일치해야 합니다 |
resolution |
문자열 | 720P |
480P, 720P, 1080P; 최상위 소문자 값은 정규화됩니다. 이 APIMaster 기본값은 공식 네이티브 기본값과 다릅니다 |
aspect_ratio |
문자열 | 16:9 |
일반 값: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4. 21:9는 네이티브 라우트에서만 가능합니다 |
ratio |
문자열 | 선택 사항 | aspect_ratio의 별칭입니다; 하나의 필드만 사용하고 충돌하는 값을 보내지 마십시오 |
size |
문자열 | 선택 사항 | 1280x720과 같은 차원 별칭입니다; 라우트별 검증이 적용됩니다. resolution과 aspect_ratio를 선호하십시오. GMI는 짧은 변이 해상도 등급과 일치해야 합니다; 네이티브는 지원되는 차원 매핑만 허용합니다 |
input_reference |
문자열 | 선택 사항 | 첫 프레임 이미지 URL입니다. 라우트 간 호환성을 위해 공개적으로 다운로드 가능한 HTTP(S) URL을 사용하십시오; 다른 첫 프레임 입력과 결합하지 마십시오 |
prompt_extend |
부울 | 네이티브 true; GMI는 생략 시 제공자 기본값을 유지합니다 |
프롬프트 재작성. 네이티브는 현재 false로 이를 안정적으로 비활성화할 수 없습니다; GMI는 명시적 부울을 전달합니다 |
watermark |
부울 | 공식 네이티브 기본값 false; GMI는 생략 시 제공자 기본값을 유지합니다 |
워터마크 스위치 |
seed |
정수 | 생략 시 무작위 | 이식 가능한 고정 범위: 1–2147483647. 네이티브는 무작위를 위한 -1도 허용합니다; 네이티브 0은 직렬화 중에 생략됩니다. GMI는 0–2147483647을 허용하고 -1을 거부합니다. 고정 시드가 동일한 출력을 보장하지는 않습니다 |
네이티브 차원 별칭은 일반적인 가로/세로 사례의 경우 832x480, 480x832, 1280x720, 720x1280, 1920x1080, 1080x1920입니다. 일부 정사각형 차원 매핑은 1:1로 축소됩니다; 다른 매핑된 차원은 여전히 화면 비율 검증에 실패할 수 있습니다. size를 사용하여 임의의 차원을 요청하지 마십시오.
라우트별 매개변수 표
GMI 필드
이들은 공통 표에 추가되는 최상위 필드입니다. GMI 어댑터는 metadata, images, image_urls, audio, generate_audio, video_urls, reference_video를 포함한 인식되지 않는 필드를 거부합니다.
| 필드 | 유형 | 필수 / 기본값 | 동작 |
|---|---|---|---|
negative_prompt |
문자열 | 선택 사항 | 최대 500자 |
first_frame |
문자열 | 선택 사항 | 공개 HTTP(S) 이미지 URL; input_reference의 대안 |
last_frame |
문자열 | 선택 사항 | 공개 HTTP(S) 최종 프레임 이미지 URL; 첫 프레임도 제공하십시오 |
reference_image |
문자열 또는 문자열[] | 선택 사항 | 1–10개의 공개 HTTP(S) 참조 이미지 URL; 여러 이미지에는 배열을 사용하십시오 |
audio_url |
문자열 | 선택 사항 | 공개 HTTP(S) 참조 오디오 URL; 제공자 미디어 검증 대상입니다 |
한 요청에서 프레임 제어 또는 참조 이미지 중 하나를 사용하십시오. 네이티브 metadata.input.media는 GMI에서 이러한 필드로 변환되지 않습니다.
Alibaba Cloud 네이티브 필드
네이티브 구조화 입력은 metadata 안에 속합니다. 공식 input 또는 parameters 객체를 최상위에 직접 보내는 것은 APIMaster 계약이 아닙니다. 항상 필수 최상위 prompt를 유지하십시오.
| 필드 | 유형 | 필수 / 기본값 | 동작 |
|---|---|---|---|
generate_audio |
부울 | 공식 네이티브 기본값 true |
출력에 오디오 트랙이 포함되는지 여부; false는 보존됩니다 |
audio |
부울 | 선택 사항 | generate_audio의 별칭; 하나만 제공하십시오 |
images |
문자열[] | 선택 사항 | reference_image 미디어 항목으로 변환됩니다; 이들은 순서가 있는 첫/마지막 프레임이 아닙니다. input_reference와 결합하지 마십시오 |
metadata |
객체 | 선택 사항 | 네이티브 input과 parameters를 감쌉니다; model을 변경할 수 없습니다 |
metadata.input |
객체 | 선택 사항 | 네이티브 입력 컨테이너 |
metadata.input.prompt |
문자열 | 선택 사항 | 네이티브 프롬프트 재정의; 최상위 프롬프트만 사용하는 것을 선호하십시오 |
metadata.input.media |
객체[] | 선택 사항 | 네이티브 미디어 모음이며 모든 항목에 type과 url이 있습니다 |
metadata.input.media[].type |
문자열 | 항목별 필수 | first_frame, last_frame, reference_image, reference_audio, file, link; reference_video는 현재 거부됩니다 |
metadata.input.media[].url |
문자열 | 항목별 필수 | 미디어 위치; 공개 HTTP(S) URL을 권장합니다. 공식 OSS 임시 URL은 별도로 유효한 업스트림 업로드 컨텍스트가 필요합니다; APIMaster는 해당 업로드 컨텍스트를 제공하지 않습니다 |
metadata.parameters |
객체 | 선택 사항 | 네이티브 매개변수 컨테이너; null이어서는 안 됩니다 |
metadata.parameters.resolution |
문자열 | 720P |
대문자 480P, 720P, 1080P |
metadata.parameters.ratio |
문자열 | 16:9 |
adaptive와 21:9를 포함한 네이티브 화면 비율 |
metadata.parameters.duration |
정수 | 5 |
2–30; -1 없음 |
metadata.parameters.audio |
부울 | 공식 네이티브 기본값 true |
출력 오디오 스위치 |
metadata.parameters.prompt_extend |
부울 | true |
file / link의 경우 true로 유지되어야 합니다; 명시적 false에는 위의 직렬화 제한이 있습니다 |
metadata.parameters.watermark |
부울 | 공식 네이티브 기본값 false |
워터마크 스위치 |
metadata.parameters.seed |
정수 | 무작위 | -1 또는 0–2147483647; 0에는 위의 직렬화 제한이 있습니다 |
최상위 네이티브 옵션은 해당 메타데이터 매개변수를 재정의합니다. 최상위 input_reference는 네이티브 미디어 배열을 대체합니다; images는 input_reference가 없을 때 참조 이미지 항목을 추가합니다. 의도하지 않은 재정의를 피하려면 하나의 입력 스타일과 하나의 매개변수 스타일을 사용하십시오. 네이티브 input 내부에서 레거시 img_url, first_frame_url, last_frame_url 또는 audio_url을 사용하지 마십시오; 어댑터는 Wan 3.0에 대해 이러한 레거시 미디어 필드를 거부합니다.
미디어 제약
아래의 공식 네이티브 미디어 규칙은 제공자 측 검증도 설명합니다; 어댑터가 URL을 받아들인다고 해서 미디어가 유효하다는 것이 증명되지는 않습니다.
| 미디어 | 제한 / 통합 참고 사항 |
|---|---|
| 첫 / 마지막 프레임 | 각각 최대 하나; 마지막 프레임에는 첫 프레임이 필요합니다. 프레임 제어를 reference_image와 혼합하지 마십시오 |
| 참조 이미지 | 최대 10개; JPEG/JPG, 투명도 없는 PNG, BMP 또는 WEBP; 각 변 240–8,000 px, 화면 비율 최대 8:1, 이미지당 최대 20 MB |
| 참조 오디오 | 네이티브: 최대 5개, WAV/MP3, 각각 1–15초, 합계 최대 15초, 파일당 최대 15 MB. GMI는 하나의 audio_url을 노출합니다 |
| 파일 / 웹 페이지 | 네이티브 전용: 최대 하나의 파일 또는 하나의 공개적으로 읽을 수 있는 페이지; file과 link를 결합하지 마십시오. 공식 파일 형식: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS, MD; 최대 100 MB, 해당되는 페이지 형식의 경우 50페이지 제한. prompt_extend: true를 유지하십시오 |
| 참조 비디오 | 공식적으로 제공되지만 현재 APIMaster 네이티브 청구 검증에 의해 차단됩니다; GMI에서는 노출되지 않습니다. 여기서 공식 API의 비디오 편집 또는 확장 예제를 사용하지 마십시오 |
공식 네이티브 결합 미디어 상한은 20개 항목입니다; 개별 및 조합 제한은 여전히 적용됩니다. 이미지 Base64 데이터 URL은 공식 네이티브 입력 형식의 일부이지만 GMI URL 검증에서는 허용되지 않습니다. 라우트 전반에서 다운로드 가능한 HTTP(S) URL을 선호하십시오.
예제
텍스트-투-비디오, 공통 필드
curl "https://apimaster.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'
첫 프레임, 공통 필드
{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}
GMI 첫 / 마지막 프레임
{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}
네이티브 첫 / 마지막 프레임 및 무음 출력
{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}
네이티브 참조 이미지 및 오디오
{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}
예제 미디어 URL을 실제 공개 파일로 바꾸십시오. 라우트별 예제는 일치하는 라우트가 필요하며 업스트림 조합 검사의 대상으로 남습니다.
응답, 폴링 및 다운로드
생성은 APIMaster 작업 ID를 반환합니다. 예:
{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}
| 필드 | 의미 |
|---|---|
id / task_id |
APIMaster 작업 식별자이며 업스트림 작업 식별자가 아닙니다 |
status |
queued, in_progress, completed, failed |
progress |
보고된 진행률; 완료 보장이 아닙니다 |
error.code / error.message |
해당하는 경우 실패 세부 정보 |
metadata.url |
완료 시 반환되는 경우 인증된 콘텐츠 주소 |
터미널 상태가 될 때까지 동일한 API 키로 10–20초마다 폴링하십시오; 생성 성공은 수락만을 의미합니다. 생성에는 몇 분이 걸릴 수 있습니다. 유료 작업을 반복적으로 생성하는 대신 수락된 작업을 폴링하십시오.
curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
-H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4
완료된 비디오를 신속하게 다운로드하여 저장하십시오; 업스트림 결과 URL은 만료될 수 있습니다. 반복 폴링은 추가 생성 청구를 발생시키지 않습니다.
청구 및 일반 오류
청구는 요청된 해상도에서 초당 과금되며, 라우트/계정 가격은 모델 카드에 표시됩니다. 제출 시 예상 요금이 예약됩니다. 네이티브 완료는 반환된 청구 가능 길이와 고정된 제출 가격을 사용합니다; GMI는 예약된 길이 계약을 따릅니다. 실패한 작업은 생성 예약을 해제/환불합니다. 오디오 끔이 더 저렴한 등급을 의미하지는 않습니다. 최종 금액은 사용 로그를 사용하십시오.
| 오류 / 증상 | 조치 |
|---|---|
duration must be an integer from 2 to 30 |
명시적 정수를 사용하십시오; -1은 통합되지 않았습니다 |
unsupported Wan request field ... |
GMI에서 지원되지 않는 필드를 제거하거나 일치하는 네이티브 라우트에 대한 액세스를 확인하십시오 |
unsupported aspect ratio |
일반 비율을 사용하십시오; 21:9는 네이티브 라우팅이 필요합니다 |
reference video requires an input-duration quote |
참조 비디오를 제거하십시오; 이 기능은 현재 차단되어 있습니다 |
prompt is required / 미디어 가져오기 실패 |
최상위 텍스트를 추가하십시오; 공개적으로 다운로드 가능한 유효한 미디어를 사용하십시오 |
prompt_extend: false 또는 seed: 0은 네이티브에서 효과가 없습니다 |
현재 직렬화 제한입니다; 양수 시드를 사용하고 재작성 비활성화에 의존하지 마십시오 |
출처: 공식 모델 정보, 공식 네이티브 API 참조, 공식 사용 가이드. 공식 기능이 동일한 필드가 모든 APIMaster 라우트에서 노출된다는 것을 의미하지는 않습니다.