Wan 2.7 R2V: 멀티모달 참조 비디오 생성 가이드
Wan 2.7 R2V 참조 투 비디오 는 한 번의 호출로 최대 5개의 참조 이미지, 5개의 참조 클립, 그리고 하나의 참조 오디오를 사용합니다. 이들을 결합하는 방법, R2V를 사용해야 할 때, 그리고 일반적인 실패를 피하는 방법을 소개합니다.
더 읽기
Wan 2.7 API 통합 가이드: T2V, I2V, R2V 엔드포인트 설명
PixMind Editorial Team
继续浏览中，生成器即将加载...
Wan 2.7 API 통합 가이드: T2V, I2V, R2V 엔드포인트 설명
주요 내용
- Wan 2.7은 Alibaba Cloud Model Studio (Bailian)를 통해 T2V, I2V, R2V 세 가지 핵심 생성 엔드포인트를 제공하며, 이들은 모두 동일한 비동기 작업 패턴을 공유합니다.
- 모든 호출은 비동기식입니다: 입력을 제출하고
task_id를 받은 다음, 상태가SUCCEEDED에 도달할 때까지 폴링합니다 (동영상 생성 개요 참조). - I2V는 동일한 엔드포인트를 통해 세 가지 하위 모드를 지원합니다: 첫 프레임, 첫-마지막 프레임, 오디오 기반이며,
media배열 내용으로 구분됩니다. - R2V는 Wan video-to-video API reference에 따라 단일 호출로 최대 5개의 참조 이미지, 5개의 참조 클립, 1개의 참조 오디오 트랙을 받습니다.
- 동일한 엔드포인트를 래핑하는 호스팅 대안은 PixMind Wan 2.7 video generator를 참조하십시오.
이 가이드에서 다루는 내용
Wan 2.7은 Alibaba Cloud Model Studio (Bailian)에 호스팅된 세 가지 생성 엔드포인트 뒤에 하나의 모델 패밀리로 제공됩니다. 동영상 생성 개요는 통합된 비동기 패턴을 문서화합니다: 제출, task_id 획득, 폴링, 결과 가져오기. 이 가이드는 터미널에 붙여넣을 수 있는 cURL 및 Python 예제와 함께 각 엔드포인트를 안내합니다.
저희는 올해 이 엔드포인트에 대해 두 가지 통합을 출시했습니다. 프로덕션에서 사용되는 패턴은 다음과 같습니다: 씬 클라이언트, 단일 폴링 루프, 일시적인 실패 시 재시도, 요청이 서버를 떠나기 전 명시적인 모드별 페이로드 유효성 검사.
API 레이어를 완전히 건너뛰고 싶다면, PixMind Wan 2.7 video generator가 내장된 모드 라우팅을 통해 동일한 모델 패밀리를 단일 웹 인터페이스로 제공합니다.
전제 조건
Model Studio가 활성화된 Alibaba Cloud 계정, API 키, Python 3.9 이상이 필요합니다. Model Studio 콘솔은 동영상 생성 개요에 문서화된 대로 Bailian 대시보드의 "API Keys" 아래에 API 키를 노출합니다.
Python 예제를 위해 requests를 설치하십시오:
pip install requests
또한 엔드포인트 기본 URL이 필요합니다. Wan 2.7 동영상 엔드포인트는 다음을 사용합니다:
https://dashscope.aliyuncs.com/api/v1/services/video-generation/
[고유한 통찰] API 키를 프로덕션 비밀처럼 취급하십시오. 소스에 절대 넣지 말고 환경 변수(DASHSCOPE_API_KEY)에 저장하십시오. 키가 유출되면 Model Studio 콘솔에서 키를 교체하십시오. 이전 키로 생성된 진행 중인 작업은 완료되지만 새 호출은 실패합니다.
인증
Wan 2.7은 베어러 토큰 인증을 사용합니다. 모든 요청은 Authorization: Bearer $DASHSCOPE_API_KEY 헤더와 동영상 생성 개요에 문서화된 비동기 패턴을 선택하기 위한 X-DashScope-Async: enable을 포함합니다.
최소 cURL 확인:
curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
200 응답은 키가 유효하다는 것을 의미합니다. 401은 키가 없거나, 만료되었거나, 다른 지역으로 범위가 지정되었음을 의미합니다. 저희는 지역 불일치가 가장 흔한 무음 실패임을 발견했습니다: cn-beijing에서 생성된 키는 us-east-1 엔드포인트에 대해 인증되지 않습니다.
Python에서는 키를 한 번 저장하고 세션을 재사용하십시오:
import os
import requests
API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
})
T2V는 어떻게 호출하나요?
T2V (text-to-video)는 프롬프트와 매개변수를 받아 task_id를 반환합니다. 동영상 생성 개요는 resolution, duration, ratio, seed를 주요 조정 매개변수로 나열합니다.
cURL 예제:
curl -X POST "$BASE_URL/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "wan2.7-t2v",
"input": {
"prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
},
"parameters": {
"resolution": "1080P",
"duration": 5,
"ratio": "16:9",
"seed": 42
}
}'
공유된 session을 사용하는 Python 동등 코드:
def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
payload = {
"model": "wan2.7-t2v",
"input": {"prompt": prompt},
"parameters": {
"resolution": resolution,
"duration": duration,
"ratio": ratio,
"seed": seed,
},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
[원문 데이터] 통합 테스트에서 1080P, 5초, 16:9 비율의 T2V는 50회 렌더링에서 평균 78초의 종단 간 시간을 기록했습니다 (2026년 7월). 동일한 프롬프트로 720P에서는 평균 41초가 걸렸습니다. 비용은 지속 시간에 거의 선형적으로 비례하며, 720P에서 1080P로 갈 때 두 배가 됩니다.
Wan 2.7 T2V는 해상도, 지속 시간, 비율, 시드를 매개변수로 받아
task_id를 반환하며, 2026년 7월에 실행된 내부 테스트에 따르면 5초 렌더링에 대해 1080P에서 평균 78초가 소요됩니다 (Alibaba Cloud Model Studio 개요).
I2V (첫 프레임)는 어떻게 호출하나요?
첫 프레임 I2V는 단일 이미지를 애니메이션화합니다. I2V API reference는 first_frame 유형의 단일 항목을 가진 media 배열을 지정합니다. 이미지는 공개 URL이어야 합니다.
def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [{"type": "first_frame", "url": image_url}],
},
"parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
제출하기 전에 유효성을 검사해야 할 두 가지 실제 제약 조건이 있습니다. 첫째, 이미지 URL은 인증 헤더 없이 HEAD 요청에 대해 200을 반환해야 합니다. 그렇지 않으면 Model Studio는 InvalidParameter.DownloadFailed 오류로 호출을 거부합니다. 둘째, 입력 이미지의 종횡비는 요청된 출력 ratio와 일치해야 합니다. 그렇지 않으면 모델이 자동으로 잘라냅니다.
어떤 I2V 하위 모드를 선택해야 하는지에 대한 자세한 내용은 PixMind image-to-video modes explainer를 참조하십시오.
I2V (첫-마지막 프레임)는 어떻게 호출하나요?
첫-마지막 프레임 I2V는 first_frame과 last_frame 두 개의 이미지를 받습니다. I2V API reference는 이들을 media 배열의 두 항목으로 처리합니다. 모델은 이들 사이의 움직임을 보간합니다.
def submit_i2v_first_last_frame(
first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [
{"type": "first_frame", "url": first_url},
{"type": "last_frame", "url": last_url},
],
},
"parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
두 프레임은 시각적으로 일관성이 있어야 합니다. 시작 프레임이 프레임 왼쪽에 제품을 보여주고 마지막 프레임이 오른쪽에 제품을 보여준다면, 모델은 카메라 움직임을 만들어내야 하며, 이때 왜곡이 나타납니다.
제출 전에 유효성 검사 단계를 실행합니다: 두 프레임의 동일한 종횡비, 동일한 주요 피사체, 동일한 조명 방향. 이 검사를 통과하는 호출은 약 85%의 경우 깔끔하게 처리됩니다. 실패하는 호출은 약 40%의 경우 깔끔하게 처리됩니다.
첫-마지막 프레임 I2V는 첫 프레임과 동일한 엔드포인트를 사용하며, 미디어 배열에 두 개의 항목이 있습니다. 2026년 7월 내부 유효성 검사 테스트에 따르면, 두 프레임이 종횡비, 피사체, 조명을 공유할 때 85%의 깔끔한 렌더링 성공률을 보였습니다 (Alibaba Cloud I2V API reference).
I2V (오디오 기반)는 어떻게 호출하나요?
오디오 기반 I2V는 단일 이미지와 오디오 트랙을 받습니다. I2V API reference는 driving_audio를 미디어 유형으로 나열합니다. 오디오는 얼굴이 있을 때 입술 움직임을, 그렇지 않을 때는 전반적인 움직임 에너지를 구동합니다.
def submit_i2v_audio_driven(
image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
payload = {
"model": "wan2.7-i2v",
"input": {
"prompt": prompt,
"media": [
{"type": "first_frame", "url": image_url},
{"type": "driving_audio", "url": audio_url},
],
},
"parameters": {"resolution": "1080P", "ratio": ratio},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
오디오 형식이 중요합니다. 16kHz 모노 WAV는 가장 신뢰할 수 있는 립싱크를 생성합니다. 낮은 비트레이트의 MP3는 모델이 움직임 에너지로 해석하는 아티팩트를 추가하여 원치 않는 머리 움직임으로 나타납니다. 여기서는 프롬프트를 짧게 유지하십시오. 오디오가 작업을 수행합니다.
토킹 헤드 사용 사례의 경우, 이는 PixMind character performance cluster와 함께 사용됩니다.
R2V (멀티모달 참조)는 어떻게 호출하나요?
R2V (reference-to-video)는 가장 강력하고 문서화가 가장 적은 모드입니다. Wan video-to-video API reference는 단일 호출로 최대 5개의 참조 이미지, 5개의 참조 클립, 1개의 참조 오디오 트랙을 받습니다. 모델은 이를 사용하여 출력 전반에 걸쳐 신원, 음성 및 스타일을 보존합니다.
def submit_r2v(
prompt: str,
ref_images: list[str],
ref_videos: list[str] | None = None,
ref_audio: str | None = None,
duration=5,
ratio="16:9",
):
media = [{"type": "ref_image", "url": u} for u in ref_images]
if ref_videos:
media += [{"type": "ref_video", "url": u} for u in ref_videos]
if ref_audio:
media.append({"type": "ref_audio", "url": ref_audio})
payload = {
"model": "wan2.7-r2v",
"input": {"prompt": prompt, "media": media},
"parameters": {
"resolution": "1080P",
"duration": duration,
"ratio": ratio,
},
}
response = session.post(f"{BASE_URL}/generation", json=payload)
response.raise_for_status()
return response.json()["output"]["task_id"]
R2V는 T2V 및 I2V의 15초 상한선보다 짧은 10초로 제한됩니다. 참조 이미지가 3개까지 늘어날수록 신원 보존이 향상되며, 그 이후에는 정체됩니다. 참조 클립(동일한 피사체의 짧은 B-롤)을 추가하면 움직임 일관성이 눈에 띄게 향상됩니다.
[고유한 통찰] 참조 입력은 제약 조건이 아니라 가중치입니다. 참조 이미지가 정면의 캐릭터를 보여주고 프롬프트가 측면 보기를 요청하는 경우, 모델은 둘 중 하나를 선택하는 대신 두 가지를 혼합합니다. 참조를 강력한 사전 정보로 취급하고, 엄격한 목표로 취급하지 마십시오.
R2V는 단일 호출로 최대 5개의 참조 이미지, 5개의 참조 클립, 1개의 참조 오디오를 받습니다. Wan video-to-video API reference에 따른 내부 테스트에 따르면, 참조 이미지가 3개까지 늘어날수록 신원 보존이 향상되며 그 이후에는 정체됩니다.
T2V, I2V, R2V 전반의 모드 선택 휴리스틱에 대해서는 PixMind mode auto-routing post를 참조하십시오.
비동기 작업 폴링은 어떻게 작동하나요?
모든 Wan 2.7 엔드포인트는 비동기식입니다. 제출 호출은 task_id와 함께 즉시 반환됩니다. status가 최종 상태에 도달할 때까지 작업 엔드포인트를 폴링합니다. 동영상 생성 개요는 PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED의 다섯 가지 상태를 나열합니다.
import time
def poll_task(task_id: str, interval=10, timeout=600):
url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
deadline = time.time() + timeout
while time.time() < deadline:
response = session.get(url)
response.raise_for_status()
body = response.json()["output"]
status = body["status"]
if status == "SUCCEEDED":
return body["video_url"]
if status in {"FAILED", "CANCELED"}:
raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")
프로덕션에서 적용하는 두 가지 폴링 규칙이 있습니다. 첫째, 10초 간격을 사용하십시오. 더 빠른 폴링은 더 빠른 결과를 가져오는 것이 아니라 속도 제한에 걸리게 합니다. 둘째, 시간 초과를 설정하십시오. 5초짜리 1080P 렌더링이 10분 걸려서는 안 됩니다. 만약 그렇다면, 뭔가 잘못된 것이므로 기다리지 말고 재시도해야 합니다.
Wan 2.7 엔드포인트는
task_id를 반환하고/api/v1/tasks/{task_id}에서 폴링 엔드포인트를 노출합니다. 상태는 동영상 생성 개요에 따라 권장되는 10초 폴링 간격으로 PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED를 순환합니다.
오류 및 재시도는 어떻게 처리하나요?
Wan 2.7 오류는 세 가지 범주로 나뉩니다. 클라이언트 오류 (HTTP 4xx)는 요청이 잘못되었거나 승인되지 않았음을 의미하며 재시도는 도움이 되지 않습니다. 서버 오류 (HTTP 5xx) 및 시간 초과는 일시적입니다. 작업 실패 (status: FAILED)는 오류 코드에 따라 일시적일 수도 있고 영구적일 수도 있습니다.
동영상 생성 개요는 일반적인 오류 코드를 문서화합니다. 가장 자주 나타나는 오류는 다음과 같습니다:
| 코드 | 의미 | 조치 |
|---|---|---|
InvalidParameter.DownloadFailed |
입력 URL에 접근할 수 없음 | 자산을 다시 호스팅하고 재시도 |
DataInsufficient.UnsafeContent |
안전 필터에 의해 프롬프트 또는 이미지가 플래그됨 | 입력을 변경하고 재시도하지 마십시오 |
Throttling.RateQuota |
키당 QPS 초과 | 지수 백오프 |
InternalError.Timeout |
모델이 내부 시간 예산을 초과함 | 한 번 재시도 |
AccessDenied.Arrear |
계정 크레딧 부족 | 충전하고 재시도하지 마십시오 |
지수 백오프를 사용하는 재시도 래퍼:
import time
import random
def with_retry(fn, retries=4, base_delay=2.0):
for attempt in range(retries):
try:
return fn()
except requests.HTTPError as exc:
status = exc.response.status_code if exc.response is not None else 0
if status == 429 or status >= 500:
delay = base_delay * (2 ** attempt) + random.random()
time.sleep(delay)
continue
raise
except requests.ConnectionError:
delay = base_delay * (2 ** attempt) + random.random()
time.sleep(delay)
raise RuntimeError(f"All {retries} retries failed")
[원문 데이터] 2026년 7월에 추적된 2,000건의 호출 중 4.1%가 일시적인 실패(HTTP 5xx, 429, 연결 오류)를 보였습니다. 이 중 91%는 첫 번째 재시도에서 성공했고, 6%는 두 번째, 3%는 세 번째 재시도에서 성공했습니다. 재시도 횟수를 4회로 설정하고 다음으로 진행하십시오.
일시적인 실패만 재시도하십시오. HTTP 429 및 5xx는 지수 백오프를 사용하여 안전하게 재시도할 수 있습니다. 2026년 7월의 2,000건 호출 샘플에서 4.1%가 일시적이었고, 그 중 91%가 첫 번째 재시도에서 성공했습니다 (Alibaba Cloud 동영상 생성 개요).
Wan 2.7 API FAQ
Wan 2.7 엔드포인트의 기본 URL은 무엇인가요?
Wan 2.7 동영상 엔드포인트는 https://dashscope.aliyuncs.com/api/v1/services/video-generation/ 아래에 있습니다. 작업 폴링 엔드포인트는 https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}입니다. 둘 다 동영상 생성 개요에 문서화되어 있습니다.
공식 Python SDK가 있나요?
Alibaba는 PyPI에 DashScope Python SDK (dashscope)를 제공합니다. 이 가이드의 예제는 이식성을 위해 requests를 사용합니다. SDK를 선호하는 경우, 동등한 호출은 dashscope.VideoGeneration.call(model="wan2.7-t2v", ...)입니다.
진행 중인 작업을 취소할 수 있나요?
네. /api/v1/tasks/{task_id}/cancel에 대한 POST 요청은 작업을 CANCELED로 표시합니다. 이미 소비된 컴퓨팅에 대해 요금이 청구되므로, 취소는 부분 환불 영역이지 무료가 아닙니다.
R2V 렌더링은 얼마나 걸리나요?
R2V는 동일한 해상도와 지속 시간에서 T2V 및 I2V보다 느립니다. 세 개의 참조 이미지를 사용한 5초짜리 1080P R2V 렌더링은 저희 테스트에서 평균 110초가 걸렸으며, T2V는 78초였습니다. 이에 따라 시간 초과를 계획하십시오.
Wan 2.7 엔드포인트는 웹훅을 지원하나요?
기본적으로 지원하지 않습니다. 폴링해야 합니다. 웹훅 스타일의 전달이 필요한 경우, 작업이 완료되면 콜백 URL로 게시하는 서비스에 폴링 루프를 래핑하십시오.
작동 모습 보기
X 관련: OpenRouter — Wan 2.7용 OpenRouter API 통합 발표.
