Wan3.0 API 뜯어보기 — 비동기 태스크 구조, 미디어 타입 7종, 30초 duration 설계

mini_knows·2026년 8월 25일

AI 트렌드·이슈

목록 보기

83/119

안녕하세요, 미니지식공간입니다.

Wan3.0 API는 동기 호출을 아예 받지 않는다. 2026년 8월 24일 알리바바 클라우드가 정식 출시한 이 영상 생성 모델은 태스크를 만들고 폴링해서 결과를 받아 오는 2단계 비동기 구조로만 동작하며, 요금도 토큰이 아니라 초당으로 매겨진다. 이 글은 공식 API 레퍼런스를 기준으로 호출 구조, 미디어 타입 제약, 파라미터 설계, 운영 시 주의점을 정리한 개발자용 노트다.

결론부터

호출은 POST .../video-synthesis로 태스크 생성 → GET .../tasks/{task_id}로 폴링하는 2단계다. X-DashScope-Async: enable 헤더가 없으면 요청이 거부된다.
duration은 영상 입력이 없을 때 2~30초, -1을 넣으면 모델이 길이를 추천한다. 30초는 Wan2.7의 15초 대비 두 배다.
요금은 초당 480P $0.05 / 720P $0.10 / 1080P $0.20이고, 2026년 8월 24일~9월 23일 일부 플랫폼에서 30% 한시 할인이 붙는다.

사건 정리 — 무엇이 언제

정식 출시일은 2026년 8월 24일이다. TechNode가 같은 날 IT Home을 인용해 정식 출시와 30% 한시 할인을 보도했고, Dataconomy도 같은 날 사양과 요금을 정리해 전했다. 그 전에는 Model Studio와 Qwen Cloud에서 신청을 받는 공개 베타였다. 베타 개시일은 Dataconomy가 2026년 8월 6일, TNGlobal이 2026년 8월 10일자 기사로 전해 자료가 엇갈리며, 공식 API 문서의 최종 수정일은 2026년 8월 6일이다. 정확한 베타 개시일은 확인 필요로 둔다.

모델명은 API에서 wan3.0-video 하나로 고정된다. 텍스트→영상, 이미지→영상(첫 프레임/첫·마지막 프레임), 레퍼런스 기반 생성이 별도 엔드포인트나 별도 모델명으로 갈라지지 않고 같은 요청 스키마 안에서 input.media의 type 값으로 구분된다. 통합 스키마라 클라이언트 코드가 단순해지지만, 뒤에서 볼 상호배타 제약을 직접 지켜 줘야 한다.

1단계: 태스크 생성

엔드포인트는 리전별로 나뉜다. 공식 문서는 모델, 엔드포인트 URL, API 키가 모두 같은 리전에 속해야 하며 교차 리전 호출은 실패한다고 명시한다. 아래는 문서에 실린 텍스트→영상 예제 그대로다.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
 -H 'X-DashScope-Async: enable' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{
 "model": "wan3.0-video",
 "input": {
 "prompt": "A kitten running on a rooftop under the moonlight, neon lights of the city flickering in the distance, cinematic quality, smooth camera movement."
 },
 "parameters": {
 "resolution": "480P",
 "ratio": "adaptive",
 "duration": 5
 }
}'

출처: Wan3.0 - Video Generation API Reference

싱가포르 리전은 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com, 베이징 리전은 {WorkspaceId}.cn-beijing.maas.aliyuncs.com이다. X-DashScope-Async: enable이 빠지면 "current user api does not support synchronous calls" 오류가 돌아온다고 문서가 못 박아 뒀다. 응답은 task_id와 task_status: PENDING만 들어 있고, 이 task_id의 유효기간은 24시간이다.

문서 입력도 같은 요청 안에서 처리된다. PPT를 넣는 경우 input.media에 type: "file"로 URL을 실어 보낸다.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
 -H 'X-DashScope-Async: enable' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{
 "model": "wan3.0-video",
 "input": {
 "prompt": "A high-end smart glasses product advertisement with a minimalist, futuristic, and fashionable style.",
 "media": [
 {
 "type": "file",
 "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
 }
 ]
 },
 "parameters": {
 "resolution": "480P",
 "ratio": "adaptive",
 "duration": 10
 }
}'

출처: 위와 동일 문서(프롬프트 문자열은 지면상 앞부분만 인용).

2단계: 폴링

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

상태는 PENDING → RUNNING → SUCCEEDED 또는 FAILED로 전이한다. 문서는 생성에 보통 1~5분이 걸리므로 15초 정도의 폴링 간격을 권한다. 중복 태스크를 만들지 말고 폴링으로 결과를 가져오라는 문구도 함께 있다.

성공 응답의 output.video_url은 24시간만 유효하다. 문서는 OSS 같은 영구 저장소로 즉시 내려받아 보관하라고 안내한다. 파이프라인을 짤 때 다운로드 단계를 폴링 성공 직후에 붙여 두지 않으면 하루 뒤 링크가 사라진다. usage 객체에는 duration, output_video_duration, fps, SR(해상도), ratio가 들어오므로 과금 검증용 로그로 쓸 수 있다.

task_id가 24시간을 넘기면 조회 결과가 UNKNOWN으로 떨어진다. 실패와 만료가 다른 상태값으로 구분되니 재시도 로직에서 두 경우를 갈라 처리해야 한다.

input.media 타입 7종과 상호배타 규칙

type	최대 개수	제약
`first_frame`	1	영상의 첫 프레임으로 고정
`last_frame`	1	영상의 마지막 프레임으로 고정
`reference_image`	10	이미지 20MB 이하, 변 240~8000px, 화면비 8:1 이내
`reference_video`	5	클립당 1~15초, 합계 15초 이내, 클립당 100MB 이하
`reference_audio`	5	클립당 1~15초, 합계 15초 이내, 15MB 이하
`file`	1	docx/xlsx/pptx/pdf/txt/md 등, 100MB·50페이지 이하
`link`	1	로그인 없이 접근 가능한 공개 웹페이지만

여기서 놓치기 쉬운 규칙이 하나 있다. reference_*/file/link 계열과 first_frame/last_frame 계열은 한 요청에서 함께 쓸 수 없다. 섞어 보내면 태스크가 FAILED로 떨어지면서 "The two modes are mutually exclusive." 메시지가 돌아온다. 요청을 만들어 주는 래퍼를 짠다면 이 검증을 클라이언트 쪽에서 먼저 걸어 두는 편이 왕복 시간을 아낀다.

file과 link도 서로 배타적이다. 문서를 넣으면서 동시에 참고 웹페이지를 붙이는 조합은 안 된다는 뜻이다. 프롬프트 안에서는 media 배열 순서에 따라 "Image 1", "Video 1" 같은 표현으로 각 자산을 지목할 수 있고, 이미지·영상·오디오는 각각 따로 번호가 매겨진다. prompt는 한국어·영어 모두 20,000자까지 받으며 초과분은 잘린다.

parameters 설계

파라미터	기본값	값
`resolution`	`1080P`	1080P / 720P / 480P
`ratio`	`adaptive`	adaptive / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
`duration`	5	2~30(영상 입력 없을 때), `-1`은 자동 추천
`audio`	true	false면 오디오 트랙 제외
`seed`	-	0~2147483647, 결과 재현용
`watermark`	false	true면 워터마크 삽입

세 가지가 실무에서 바로 걸린다. 첫째, resolution 기본값이 1080P다. 명시하지 않고 호출하면 초당 $0.20짜리 최고 단가로 과금된다는 뜻이니, 테스트 단계에서는 480P를 명시적으로 넣는 습관이 필요하다. 둘째, duration 기본값은 5초라 30초를 쓰려면 반드시 값을 지정해야 한다. 셋째, 영상을 입력으로 넣는 경우 입력 영상 길이와 출력 길이의 합이 30초를 넘을 수 없다.

audio는 껐다 켜도 요금이 달라지지 않는다고 문서가 명시한다. 오디오가 필요 없는 파이프라인에서 비용을 아끼려고 끄는 것은 의미가 없고, 후처리 부담을 줄이는 용도로만 쓰면 된다. seed는 결과 재현용이므로 A/B로 프롬프트만 바꿔 비교할 때 고정해 두면 변인 통제가 된다.

비용 계산

초당 단가는 480P $0.05, 720P $0.10, 1080P $0.20이다(Dataconomy 2026년 8월 24일 보도). 토큰이 아니라 출력 영상 길이로 매겨지므로 계산이 단순하다. 1080P 30초 한 편이 $6.00, 분당으로 환산하면 $12다.

시나리오	계산	비용
480P 5초 프로토타입 100회	0.05 × 5 × 100	$25
720P 15초 소셜 클립 200편	0.10 × 15 × 200	$300
1080P 30초 광고 30편	0.20 × 30 × 30	$180

위 세 줄은 공개된 초당 단가에 길이와 편수를 곱한 값이며, 2026년 8월 24일부터 9월 23일까지 적용되는 30% 한시 할인은 반영하지 않았다(TechNode 보도). 할인 적용 대상 플랫폼은 자료에 명시가 없어 확인 필요다. Dataconomy는 비교군으로 구글 Veo 3.1 표준 서비스의 초당 $0.40을 들었는데, 이는 단가 비교일 뿐 품질 비교가 아니다.

비용 설계에서 실질적으로 중요한 것은 재시도다. 생성이 1~5분 걸리고 결과가 마음에 들지 않으면 통째로 다시 만들어야 하므로, 480P에서 프롬프트를 확정한 뒤 최종본만 1080P로 올리는 2단계 워크플로우가 단가 대비 효율이 좋다. 같은 회사의 언어 모델 API 요금 구조를 함께 보고 싶다면 Qwen3.8-Max API 정리도 참고하시면 좋다.

확인되지 않은 것들

Dataconomy는 Wan3.0의 성능이 아직 독립적으로 벤치마크되지 않았고 품질 주장이 회사 발표에 의존한다고 지적했다. 30초 길이, 문서 입력, 파라미터 스펙은 공식 문서로 확인되는 사실이지만 "샷 간 일관성이 개선됐다"는 서술은 알리바바 클라우드의 자사 발표다. 도입 판단은 자체 프롬프트 세트로 돌려 보고 내리는 편이 안전하다.

가중치 공개 여부도 갈린다. Dataconomy는 알리바바가 Wan 시리즈에서 유지해 온 오픈소스 기조를 이번에 접고 가중치를 비공개로 돌렸다고 보도했다. 단일 매체 보도라 공식 확인이 더 필요한 대목이다. 접근 경로 역시 현재는 Model Studio와 Qwen Cloud에서 신청을 거치는 구조이고, 소비자용 wan.video는 회원 전용으로 준비 중이라고 같은 매체가 전했다. 가중치 공개 시점이 쟁점이 됐던 다른 영상 모델 사례는 FLUX 3 정리에서 다룬 적이 있다.

자주 묻는 질문

Q. Wan3.0 API를 동기 호출로 쓸 수 있나?
없다. 공식 문서는 HTTP 요청이 비동기 호출만 지원한다고 명시하며, X-DashScope-Async: enable 헤더가 빠지면 동기 호출을 지원하지 않는다는 오류를 반환한다. 태스크 생성과 폴링 2단계로 구현해야 한다.

Q. 기존 Wan2.7 코드를 그대로 쓰면 되나?
모델명이 wan3.0-video로 바뀌고 input.media의 타입 체계와 상호배타 규칙이 이 문서 기준으로 정의돼 있으므로, 요청 본문을 문서와 대조해 재작성하는 편이 안전하다. Wan2.7용 API 레퍼런스는 별도 문서로 유지되고 있어 두 스키마를 직접 비교해 볼 수 있다.

Q. 생성된 영상 URL은 얼마나 보관되나?
24시간이다. 그 뒤에는 자동 삭제되므로 폴링이 SUCCEEDED로 바뀐 직후 OSS 같은 영구 저장소로 옮기는 단계를 파이프라인에 반드시 넣어야 한다. task_id 역시 24시간이 지나면 조회 시 UNKNOWN을 반환한다.

마무리

정리하면 Wan3.0은 통합 스키마 하나로 텍스트·이미지·영상·오디오·문서 입력을 모두 받고, 2단계 비동기 호출과 초당 과금으로 동작한다. 구현에서 걸리는 지점은 리전 일치, 모드 상호배타, 1080P 기본값, 24시간 URL 만료 네 가지다. 성능 주장은 아직 자사 발표 단계이니 한시 할인 기간에 실제 워크로드로 검증해 보시길 권한다.

출처