Vidu AI API 가이드: Image-to-Video 및 Reference Video 활용법

Vidu AI API는 단 한 번의 요청으로 정지 이미지를 모션 클립으로 변환하며, 레퍼런스 비디오 모드를 사용하면 기존 클립의 움직임을 정지 이미지에 그대로 적용할 수 있습니다. 이 튜토리얼에서는 페이로드 구조, 파라미터 튜닝, 실무 구현 체크리스트를 포함하여 TokenLab 통합 API를 통해 두 가지 기능을 모두 사용하는 방법을 안내합니다.

핵심 요약

• Vidu의 이미지-투-비디오 엔드포인트는 정지 프레임에서 사실적인 움직임을 생성하며, 레퍼런스 비디오 모드는 한 비디오의 정밀한 모션 패턴을 대상 이미지의 콘텐츠에 복사합니다.
• TokenLab은 Vidu를 비롯해 Seedance, Veo 3, Kling, Hailuo, PixVerse V6와 같은 다양한 비디오 모델을 하나의 일관된 API로 제공하므로, 통합 코드를 변경하지 않고도 품질, 속도, 비용을 비교할 수 있습니다.
• motion_intensity, num_frames, reference_video와 같은 파라미터는 출력 스타일, 지속 시간, 충실도를 직접 제어하며, 이를 조정하면 생성 지연 시간과 결과물의 품질에 영향을 줍니다.
• 가격과 모델 가용성은 자주 변경되므로, TokenLab 모델 디렉토리와 가격 비교 페이지(모두 2026년 7월 7일 기준)에서 최신 정보를 항상 확인하세요.

Vidu의 이미지-투-비디오 및 레퍼런스 비디오 모드 이해하기

Vidu의 이미지-투-비디오 파이프라인은 정적 입력 이미지를 첫 번째 프레임으로 처리하고, 비디오 데이터에서 학습된 모션 사전 지식을 사용하여 나머지 프레임을 채웁니다. 모델은 장면 의미론과 일치하는 광학 흐름 및 외형 변화를 예측하여 짧은 비디오 클립(num_frames 및 선택한 해상도에 따라 보통 2~10초)을 출력합니다.

모션 전송 또는 비디오 가이드 생성이라고도 하는 레퍼런스 비디오 모드는 추가적인 reference_video 파라미터를 허용합니다. 모델은 레퍼런스 클립에서 모션 벡터를 추출하여 정지 이미지의 콘텐츠에 적용합니다. 예를 들어, 한 비디오의 댄서 움직임을 인물 사진에 전송하거나, 제품 쇼케이스의 카메라 팬(pan) 효과를 다른 제품 이미지에 매핑할 수 있습니다. 두 모드 모두 TokenLab에서 동일한 API 엔드포인트를 공유하며, 유일한 차이점은 요청 시 reference_video 필드의 포함 여부입니다.

프롬프트에서 움직임을 환각적으로 생성하는 텍스트-투-비디오 모델과 달리, Vidu의 이미지 조건부 방식은 시작 프레임을 정밀하게 제어할 수 있으며, 레퍼런스 비디오를 사용하면 정확한 모션 안무까지 제어할 수 있습니다. 덕분에 정적 컨셉 아트를 애니메이션화하거나, 제품 사진에 부차적인 움직임을 추가하거나, 단일 레퍼런스로 캐릭터 애니메이션 테스트를 만드는 데 적합합니다. 모델이 실제 첫 번째 프레임을 기반으로 작업하기 때문에 생성된 클립은 입력 이미지의 시각적 정체성을 유지하며, 프롬프트 전용 파이프라인에서 흔히 발생하는 형태 왜곡 문제를 방지합니다.

TokenLab 계정 및 API 키 설정

TokenLab을 통해 Vidu를 사용하려면 활성화된 계정과 API 키가 필요합니다.

1. tokenlab.sh에서 가입하세요.
2. 대시보드로 이동하여 API Keys 메뉴에서 API 키를 생성하세요.
3. 키를 안전하게 보관하세요. 모든 요청 시 Bearer 토큰으로 전송됩니다.

TokenLab의 통합 API를 사용하면 페이로드의 model 필드만 변경하여 비디오 모델 간에 전환할 수 있습니다. Vidu는 vidu라는 이름으로 식별됩니다. Seedance나 Veo 3와 같은 모델을 위해 작성된 기존 통합 코드는 구조 변경 없이 Vidu에서도 작동합니다.

TokenLab으로 첫 Vidu API 요청하기

기본적인 이미지-투-비디오 요청은 정적 이미지 URL과 생성 파라미터 세트를 전송합니다. 다음은 curl을 사용한 예시입니다:

curl -X POST "https://api.tokenlab.sh/v1/video/generate" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu",
    "image_url": "https://example.com/portrait.jpg",
    "motion_intensity": 0.7,
    "num_frames": 120,
    "resolution": "1080p"
  }'

레퍼런스 비디오 모드의 경우, 짧은 모션 클립을 가리키는 reference_video 파라미터를 추가하세요:

{
  "model": "vidu",
  "image_url": "https://example.com/portrait.jpg",
  "reference_video": "https://example.com/dance_reference.mp4",
  "motion_intensity": 0.8,
  "num_frames": 120
}

API는 생성이 완료될 때까지 폴링할 수 있는 video_url이 포함된 JSON 객체를 반환합니다. TokenLab은 폴링을 피하기 위해 웹훅 콜백도 지원하며, 이는 프로덕션 환경에서 권장되는 방식입니다.

품질 및 속도를 위한 파라미터 튜닝

Vidu 엔드포인트는 모션 사실성, 출력 지속 시간, 처리 시간에 영향을 주는 여러 파라미터를 허용합니다. 아래 표는 가장 중요한 파라미터를 요약한 것입니다.

파라미터	타입	설명	일반적인 범위
motion_intensity	float	움직임의 강도를 제어합니다. 낮은 값은 미묘한 움직임을, 높은 값은 더 극적인 동작을 생성합니다.	0.0 – 1.0
num_frames	int	생성할 프레임 수입니다. 출력 지속 시간은 num_frames / fps이며, 기본 fps는 24입니다. 값이 클수록 생성 시간이 늘어납니다.	48 – 240
resolution	string	출력 해상도입니다. 720p 및 1080p를 지원합니다. 해상도가 높을수록 비용이 많이 들고 시간이 더 걸립니다.	720p, 1080p
reference_video	string	모션 전송을 위한 레퍼런스 비디오의 URL입니다. 생략 시 모델이 자율적으로 움직임을 생성합니다.	URL
style_strength	float	입력 이미지의 시각적 스타일과 레퍼런스 모션 중 어느 쪽을 더 따를지 결정합니다. 1.0은 이미지 스타일을 유지하며, 낮은 값은 레퍼런스 비디오의 스타일이 약간 반영되도록 합니다.	0.0 – 1.0

전체 길이로 확장하기 전에 짧은 클립(48~60 프레임)으로 이러한 파라미터를 테스트하면 시간과 비용을 모두 절약할 수 있습니다. TokenLab 가격 페이지에서 해상도와 프레임 수에 따라 달라지는 실시간 생성 비용을 확인할 수 있습니다. 모델 디렉토리에는 Vidu가 호스팅되는 공식 제공업체(Replicate, fal 등)도 나열되어 있으며, 이들의 가격은 독립적으로 책정됩니다. 최신 요금은 Replicate 가격 및 fal 가격 페이지를 확인하세요(2026년 7월 7일 기준).

실무 구현 체크리스트

라이브 서비스 전, 다음 체크리스트를 사용하여 통합이 프로덕션 준비를 마쳤는지 확인하세요.

• API 키 범위가 올바르게 설정됨 – 키에 비디오 생성에 필요한 것 이상의 광범위한 권한이 없음.
• 입력 이미지 검증 완료 – 이미지 URL이 공개적으로 접근 가능하며 최소 512×512 픽셀 이상임. 모델은 선명하고 조명이 좋은 얼굴이나 사물에서 가장 잘 작동함.
• 레퍼런스 비디오 준비 완료 – 모션 전송 사용 시, 레퍼런스 클립은 짧고(2~5초), 잘 크롭되었으며, 장면 전환 없이 단일 연속 동작을 포함함.
• 파라미터 튜닝 완료 – motion_intensity와 num_frames가 샘플에서 테스트되었으며, 선택한 균형이 지연 시간 예산 및 시각적 품질 기준을 충족함.
• 폴링 또는 웹훅 구성 완료 – 클라이언트가 video_url 상태를 폴링하거나 완료 웹훅을 수신하여 메인 스레드가 차단되지 않도록 함.
• 오류 처리 구현 완료 – 5xx 오류 발생 시 적절히 재시도하고, 디버깅을 위해 모든 4xx 응답을 기록함.
• 비용 모니터링 활성화 – TokenLab 대시보드에 지출 한도가 설정되어 있으며, 비용 변화에 따라 가격 비교 페이지를 정기적으로 참조함.
• 모델 대체 방안 고려 – Vidu를 일시적으로 사용할 수 없는 경우, Seedance나 Veo 3로 전환하기 위해 TokenLab에서 model 필드만 변경하면 됨.

이 단계를 따르면 비디오 모델 공급 상황이 변하더라도 파이프라인의 안정성을 유지할 수 있습니다.

Vidu와 다른 비디오 모델 비교

TokenLab의 통합 API를 사용하면 통합 코드를 다시 작성하지 않고도 Vidu를 다른 여러 비디오 생성기와 비교 테스트할 수 있습니다. 작성 시점(2026년 7월 7일) 기준 주요 대안은 Seedance, Veo 3, Kling, Hailuo, PixVerse V6이며, 모두 동일한 엔드포인트에서 사용할 수 있습니다. 각 모델은 고유한 강점이 있습니다:

• Seedance – 높은 프레임 속도와 유연한 캐릭터 애니메이션에 탁월하며, 댄스 및 액션 장면에 선호됩니다.
• Veo 3 – 영화 같은 카메라 움직임과 장면 구성을 생성하며, 제품 비디오 및 단편 영화에 강점이 있습니다.
• Kling – 사실적인 인간의 움직임과 립싱크에 최적화되어 있으며, 말하는 아바타 생성에 유용합니다.
• Hailuo – 스타일화된 애니메이션 효과에 집중하며, 모션 그래픽에 적합합니다.
• PixVerse V6 – 대량의 소셜 미디어 클립을 위한 속도와 품질의 균형을 제공합니다.

사이드-바이-사이드 출력 샘플과 사용 사례 권장 사항을 포함한 이 모델들에 대한 자세한 분석은 2026년 최고의 AI 비디오 모델 API 기사에서 확인할 수 있습니다. 비용에 따라 제공업체를 라우팅해야 하는 개발자를 위해 OpenRouter 비교 가이드에서 TokenLab이 다중 제공업체 액세스를 추상화하고 비용을 최소화하는 방법을 설명합니다.

FAQ

1. Vidu는 이미지와 함께 텍스트 프롬프트를 지원하나요?
   Vidu는 기본적으로 이미지 조건부 모델입니다. 이미지가 첫 번째 프레임 역할을 하고 모션 사전 지식이 움직임을 결정합니다. 일부 제공업체는 스타일을 조정하기 위한 선택적 텍스트 힌트를 허용할 수 있지만, TokenLab을 통한 API는 현재 prompt 필드를 허용하지 않습니다. 출력에 영향을 주는 가장 좋은 방법은 motion_intensity, num_frames를 조정하고, 무엇보다 적절한 레퍼런스 비디오를 사용하는 것입니다.

2. 일반적인 생성 시간은 얼마나 걸리나요?
   생성 지연 시간은 num_frames, 해상도, 제공업체 부하에 따라 다릅니다. 720p 2초 클립(48 프레임)은 일반적으로 TokenLab에서 15~30초 내에 완료됩니다. 1080p 5초 클립(120 프레임)은 60~90초가 소요될 수 있습니다. 시간이 중요한 애플리케이션에는 웹훅 전달을 권장합니다.

3. 로컬에 호스팅된 이미지나 비디오를 사용할 수 있나요?
   TokenLab은 image_url 및 reference_video에 대해 공개적으로 접근 가능한 URL을 요구합니다. 클라우드 스토리지 버킷(예: 사전 서명된 URL이 있는 Amazon S3)에 파일을 업로드하거나 임시 호스팅 서비스를 사용할 수 있습니다. Vidu의 기반 제공업체(Replicate, fal) 또한 자산 가져오기를 위해 URL을 요구합니다.

TokenLab에서 Vidu 시작하기

Vidu AI API는 이미지-투-비디오 및 모션 전송 프로젝트에 바로 사용할 수 있습니다. TokenLab 계정을 만들고 API 키를 받아 오늘 첫 번째 테스트 요청을 보내보세요. TokenLab 모델 디렉토리를 탐색하여 Vidu를 선택하고 다른 비디오 생성기와 비교하거나, 가격 비교 페이지를 확인하여 비용을 최적화하세요. 하나의 API로 전체 비디오 모델 라인업에 액세스할 수 있으며, 별도의 통합 전환이 필요하지 않습니다.