Skip to main content

개요

**Wan (Tongyi Wanxiang)**은 Alibaba Cloud의 동영상 생성 모델 시리즈입니다. APIYI는 DashScope 패스스루 채널을 통해 Alibaba Cloud Model Studio에 직접 연결되므로, sk-로 시작하는 단일 APIYI Key만 있으면 별도의 Alibaba Cloud 계정 없이도 모든 Wan 동영상 기능을 사용할 수 있습니다. 현재 주력 모델은 Wan2.7이며, 다음 네 가지 핵심 사용 사례를 지원합니다:
🎬 핵심 강조: 네 가지 기능은 모두 동일한 비동기 엔드포인트와 동일한 요청 구조를 사용합니다. model 필드만 바꾸어 사용 사례를 전환할 수 있습니다. 720P / 1080P 해상도와 2-15초 정수 길이를 기본 지원하며, wan2.7-i2v은 립싱크를 위한 구동 오디오도 지원합니다. 숏폼 동영상 제작, 이커머스 소재, 디지털 휴먼 내레이션, 크리에이티브 마케팅에 적합합니다.

텍스트-투-비디오 API

wan2.7-t2v 순수한 텍스트 prompt만으로 동영상을 생성하며, 가장 간단한 진입점입니다.

이미지-투-비디오 API

wan2.7-i2v 첫 프레임 + 선택적 구동 오디오를 사용해 립싱크 / 랩을 지원합니다.

레퍼런스-투-비디오 API

wan2.7-r2v 레퍼런스 이미지/비디오의 피사체 특징을 유지하며, 음성 레퍼런스를 지원합니다.

비디오 편집 API

wan2.7-videoedit 레퍼런스 이미지로 동영상을 편집합니다: 의상 교체, 배경 교체 등.

시각 API 테스트

iCover 시각 테스트 도구에서 이 엔드포인트를 직접 디버깅할 수 있습니다 — 코드가 필요하지 않습니다.

비동기 작업 조회 / 다운로드

제출한 동영상 작업을 확인하고 APIYI 콘솔에서 동영상 링크를 다운로드할 수 있습니다 — API 외부의 조회 항목입니다.

Wan을 APIYI에서 사용하는 이유

모든 기능을 위한 하나의 Key

Alibaba Cloud 가입도, 리전 설정도, 환경 변수도 필요 없습니다. 하나의 APIYI Key로 네 가지 Wan2.7 기능과 HappyHorse 시리즈를 모두 호출할 수 있습니다.

직접 접속, VPN 불필요

api.apiyi.com에 바로 연결할 수 있으며, 중국 본토 데이터 센터와 가정용 네트워크 모두에서 접속 가능하고, Alibaba Cloud 리전 엔드포인트를 구성할 필요가 없습니다.

실패 시 과금 없음

failed로 끝나는 작업(접근할 수 없는 미디어 URL, 민감한 prompt, 상위 용량 부족 등)은 과금되지 않으므로, 자유롭게 재시도할 수 있습니다.

DashScope 프로토콜 패스스루

요청 본문은 Alibaba Cloud의 기본 DashScope 프로토콜과 1:1로 매핑되므로 공식 문서를 따라 마이그레이션할 수 있으며, 응답은 손쉬운 폴링을 위해 정규화됩니다.

핵심 기능

4-in-1 비동기 엔드포인트

t2v / i2v / r2v / video-edit가 POST /wan/api/v1/...video-synthesis을 공유합니다. 제출하면 task_id를 받고, 폴링한 뒤 다운로드합니다. 간편한 일괄 관리가 가능합니다.

오디오 기반 립싱크

wan2.7-i2vdriving_audio을 지원하여 정적인 인물 사진이 오디오의 입 모양과 리듬에 맞게 동기화됩니다. 랩 / 내레이션 / 디지털 휴먼에 적합합니다.

다중 대상 참조

wan2.7-r2v는 참조 이미지 + 참조 동영상(총 5개까지)을 혼합하며, prompt에서 “image 1 / video 1”로 참조하고 음성 참조도 지원합니다.

다양한 해상도와 길이

720P / 1080P 해상도, 2-15초 정수 길이를 지원합니다. prompt_extend 스마트 재작성은 짧은 prompt의 품질을 더욱 향상합니다.

지원되는 모델

wan2.7-videoedit는 이미지를 사용하여 동영상을 편집하는 용도입니다. 별도의 wan2.7-image-pro이미지 모델이며(/v1/images/generations를 사용함) 이 동영상 엔드포인트의 범위 밖이므로 서로 혼동하지 마십시오. 레거시 Wan2.6 시리즈는 기록 버전을 참조하십시오.

⚠️ 엔드포인트 선택(가장 중요)

APIYI는 두 경로를 제공하지만, DashScope 패스스루 엔드포인트만 Wan의 모든 기능을 완전히 지원합니다:
어떤 문서나 예시에서 Wan 동영상 작업을 /v1/videos를 통해 제출하라고 하더라도, 무시하십시오. 그 경로의 i2v / r2v media 필드에 대한 적응은 불완전하며 상위 오류 [InvalidParameter] Field required: input.media를 유발합니다. 모든 Wan 동영상 생성 요청은 /wan/api/v1/...video-synthesis로 전송됩니다.

비동기 호출 흐름

전체 흐름은 세 가지 비동기 단계입니다: 작업 생성 → 상태 폴링 → 동영상 다운로드.
1

작업을 생성합니다

POST /wan/api/v1/services/aigc/video-generation/video-synthesis 헤더 X-DashScope-Async: enable를 사용합니다. 즉시 task_id를 반환합니다.
2

상태를 폴링합니다

GET /v1/tasks/{task_id} (Authorization 포함), 5~10초마다 한 번씩(절대 3초 미만으로는 하지 마십시오), statuscompleted가 될 때까지 반복합니다.
3

동영상을 다운로드합니다

응답의 result_url에서 mp4를 직접 GET합니다. Authorization 헤더를 보내지 마십시오(OSS 서명된 직접 링크이므로 Auth를 추가하면 403이 발생합니다).

작업 상태 참조

status의 최상위 GET /v1/tasks/{task_id} 필드(APIYI에서 이미 정규화됨):

전체 Python 클라이언트

핵심 매개변수 설명

제출 시 본문은 DashScope의 중첩 구조를 사용합니다: { model, input: { prompt, media[] }, parameters: {...} }.

input 필드

media[] 유형

각 미디어 객체에는 최소 type + url가 필요합니다. url는 GET으로 직접 가져올 수 있는 공개 https 링크여야 합니다(로컬 파일은 먼저 OSS / CDN에 업로드하십시오).

parameters 필드

duration정수 5여야 하며, 문자열 "5"이 아니어야 합니다. 그렇지 않으면 cannot unmarshal string into Go struct field ... of type int가 발생합니다. resolution대문자로 쓰는 것(720P)이 더 안정적입니다.

Wan과 HappyHorse 선택하기

Wan과 HappyHorse는 모두 Alibaba 동영상 모델이며 같은 endpoint와 schema를 공유합니다(model 이름만 바꾸면 교체할 수 있습니다). 다만 강점은 다릅니다:
립싱크 / 랩 / 디지털 휴먼 나레이션이 필요합니다wan2.7-i2v을 선택합니다(오디오 구동을 지원하는 유일한 모델입니다). 대상을 일관되게 유지하기 위해 많은 참조 이미지가 필요합니다HappyHorse r2v (최대 9개 이미지)를 고려합니다.

모범 사례

1

먼저 720P / 5초에서 반복합니다

개발 중에는 저해상도 짧은 클립으로 prompt와 카메라 방향을 빠르게 검증한 뒤, 최종 확정 후에는 720P / 1080P와 더 긴 길이로 확장하여 비용과 대기 시간을 줄입니다.
2

항상 prompt_extend을 활성화합니다

prompt_extend: true짧은 prompt의 품질을 분명히 향상시키며, 생성 시간은 몇 초만 추가로 듭니다.
3

5-10초마다 폴링합니다

3초보다 짧으면 안 됩니다(요청 제한이 걸립니다). 또한 긴 작업을 무기한으로 차단하지 마십시오. 720P / 5초는 일반적으로 70-140초가 걸리며, 1080P / 더 긴 클립은 5분을 넘길 수 있습니다.
4

최후 안전장치로 20분 클라이언트 타임아웃을 설정합니다

1080P 또는 10초를 넘는 클립은 눈에 띄게 더 느립니다. 폴링 루프에 20분의 최후 안전장치 타임아웃을 두십시오.
5

result_url을 받는 즉시 다운로드합니다

result_url 기본적으로 24시간 후 만료되며 OSS 서명된 직접 링크이므로, 다운로드할 때는 Authorization 헤더를 보내지 마십시오. 프로덕션에서는 항상 자체 OSS / CDN에 다시 저장하십시오.
6

제출을 멱등하게 만듭니다

실패한 작업은 과금되지 않지만, 같은 작업을 다시 제출하면 다시 과금됩니다. 앱 레이어에서 “business ID → task_id” 매핑을 유지하여 우발적인 과금을 방지하십시오.

오류 코드 및 재시도

오류는 두 단계에서 발생하며 서로 다르게 처리됩니다:
권장 클라이언트 동작: HTTP 5xx / 네트워크 오류에 대해 지수 백오프 재시도(1초 / 4초 / 16초)를 사용하십시오. HTTP 4xx는 재시도 없이 즉시 노출하십시오. [InvalidImageUrl]가 있는 failed 작업은 다시 시도할 수 있으며(일시적인 네트워크 문제일 수 있음), [InvalidParameter] / 민감한 단어는 재시도하면 안 됩니다.

자주 묻는 질문

/v1/videos는 Wan의 i2v / r2v를 불완전하게 지원하는 OpenAI 플랫 스타일 엔드포인트입니다. media 같은 미디어 필드는 누락되고, 상위 Alibaba Cloud는 [InvalidParameter] Field required: input.media를 반환합니다. 모든 Wan 동영상 생성 요청은 /wan/api/v1/services/aigc/video-generation/video-synthesis로 가며, 조회는 항상 /v1/tasks/{task_id}로 갑니다.
엔드포인트에 “이것은 비동기 작업이므로, task_id를 즉시 반환하고 차단하지 마십시오.”라고 알려줍니다. 모든 생성 요청에 필수입니다. 생략하면 current user api does not support synchronous calls가 반환됩니다. 조회 호출(GET)에는 이 헤더가 필요하지 않습니다.
APIYI는 모든 동영상 작업 조회를 /v1/tasks/{task_id}로 표준화합니다. 작업을 생성할 때 어떤 경로를 사용했든 이 하나의 엔드포인트로 조회하며, 응답의 최상위 status / progress / result_url / error 필드는 일관됩니다.
Authorization 헤더를 제거하십시오. result_url는 이미 Alibaba Cloud OSS의 사전 서명된 직접 링크이므로, APIYI Key를 추가하면 OSS가 이를 거부합니다.
링크는 기본적으로 24시간 동안 유효합니다. 만료 후에는 /v1/tasks/{task_id}를 다시 GET하면 보통 새 result_url를 받지만, task_id 자체의 조회 유효 기간도 24시간입니다(그 이후에는 UNKNOWN를 반환합니다). 장기 보관이 필요하면 가능한 한 빨리 자체 저장소로 다운로드하십시오.
아닙니다. 상위 Alibaba Cloud가 보고하는 진행률은 거칠게 구분됩니다(0% / 10% / 30% / 100% 구간만 있음). status가 여전히 in_progress인 한 기다리십시오. 보통 30%에서 100%로 바로 뛰어오릅니다.
실제로는 요청 제한에 걸리지 않고 한 번에 48개 작업을 제출할 수 있습니다. 운영 환경에서는 동시에 활성화된 작업을 ≤10으로 유지하십시오. 그 이상은 대기열로 들어갑니다. 조회 API의 기본 RPS는 꽤 높지만, 510초 폴링 간격을 여전히 권장합니다.
status=failed는 과금되지 않습니다. 다만 같은 작업을 다시 제출하면 다시 과금되므로 멱등하게 만드십시오. 테스트 중에는 prompt_extend을 끄고 720P / 5초 / 짧은 prompt를 사용해 단가를 낮출 수 있습니다.
네. Wan2.6 시리즈(wan2.6-r2v-flash 포함)는 여전히 호출 가능 목록에 있으며, Wan2.7과 동일한 프로토콜을 사용합니다. model 이름만 바꾸면 됩니다. 이전 버전을 참조하십시오.

그룹 설정

Wan 및 HappyHorse 시리즈는 하나의 Wan&HappyHorse 그룹을 공유합니다 — 하나의 토큰으로 두 시리즈를 모두 호출할 수 있습니다. 동영상 모델은 초당 과금되므로, 토큰이 정상적으로 라우팅되려면 두 가지 조건을 충족해야 합니다:
  1. 과금 모델: 종량제 Priority 또는 종량제를 선택합니다 — 동영상은 초당 과금되므로, 요청당 과금 토큰은 라우팅할 수 없습니다
  2. 그룹: Wan&HappyHorse를 포함하는 그룹을 선택합니다
토큰 생성 대화상자: 과금 모델이 종량제 Priority로 설정되어 있고, 그룹 드롭다운에 Wan&HappyHorse(요율 0.14배)가 표시되며, 하나의 토큰으로 Wan2.7과 HappyHorse를 모두 사용할 수 있음

Create Token: set billing model to Pay-as-you-go Priority and group to Wan&HappyHorse (0.14x) to call every Wan2.7 and HappyHorse video model (the screenshot shows the group's former name Wan, since renamed to Wan&HappyHorse)

가격

기본 가격 = Alibaba 공식 가격의 98%(이해하기 쉬움)

콘솔에서 Wan&HappyHorse 그룹은 0.14x의 요율을 표시하며, 이는 내장 RMB 가격 단위를 사용합니다. APIYI는 USD로 1:7의 고정 환율을 적용해 과금하므로, 실제 환산은 다음과 같습니다:
즉, **기본 가격 = Alibaba 공식 가격의 98%**입니다. Alibaba에서 직접 구매하는 것보다 저렴하며, 직접 구축해야 할 해외 연동도 없습니다.
환산: 초당 USD 가격 = 공식 RMB 가격 × 0.14(즉, × 0.98 ÷ 7). 예를 들어, 1080P의 공식 가격이 ¥1.0/s이면 → $0.14/s이며, 콘솔에 표시된 0.14x와 정확히 같습니다.

가격 상세(기본 가격, 초당 과금)

Wan2.7 텍스트-동영상 / 이미지-동영상 / 참조-동영상은 동일한 가격이며, 두 단계는 720P / 1080P입니다(480P는 지원하지 않습니다):
  • wan2.7-r2v은 기본값이 1080P이며, 참조 미디어에 동영상이 포함된 경우 길이는 최대 10초로 제한됩니다.
  • wan2.7-videoedit(동영상 편집) 출력 길이는 원본 동영상을 따르며, duration가 아니라 실제 출력 초 단위로 과금됩니다.
  • 표시된 가격은 **기본(공식 가격의 98%)**이며, 최대 충전 보너스를 적용하면 실제 가격은 대략 표의 값 ÷ 1.2입니다(예: 1080P 5초 $0.70 → 약 $0.58).

더 낮은 실효 가격을 위한 누적 충전 보너스

충전 보너스 프로그램에 가입하면 충전된 잔액이 최대 ~1.2x까지 늘어나 실효 가격을 더 낮출 수 있습니다:
따라서 대량 이용자는 **공식 가격의 ~81.6%**까지 낮출 수 있습니다.
  • 과금 기준 = **해상도 등급 × 길이(초)**이며, 실패한 작업은 과금되지 않습니다.
  • 1:7은 고정 정산 환율이며(우대 환율이 아닙니다), 모든 USD 충전에 동일하게 적용됩니다.
  • 최고 보너스 등급과 적용 가능한 채널은 충전 보너스를 참조하십시오. 최신 요율은 콘솔이 기준입니다.

관련 문서

텍스트-투-비디오 플레이그라운드

wan2.7-t2v 실시간 디버깅 + 코드 예시

이미지-투-비디오 플레이그라운드

wan2.7-i2v 첫 프레임 + 드라이빙 오디오

레퍼런스-투-비디오 플레이그라운드

wan2.7-r2v 다중 객체 레퍼런스 + 음성

비디오 편집 플레이그라운드

wan2.7-videoedit 의상 / 배경 교체

이전 버전 (Wan2.6)

Wan2.6 시리즈 및 마이그레이션 노트

HappyHorse 시리즈

또한 Alibaba 기반이며, 나란히 비교하는 선택 가이드입니다.
Alibaba Cloud 공식 문서(참고): help.aliyun.com/zh/model-studio/text-to-video-api-reference. 질문이나 제안이 있으시면 APIYI 콘솔에서 티켓을 여십시오.