Vidu API 가이드：MoE 모델 & Q 시리즈 접근

한 줄로 요약하자면: 하나의 APIMart 설정을 통해 더 어려운 프롬프트 로직에는 Vidu MoE, 최종 출력에는 Q3 Pro, 저비용 테스트에는 Q3 Turbo를 사용하세요.**

바로 실행에 옮길 수 있는 요약은 다음과 같습니다:

• 하나의 API 키와 하나의 주요 요청 흐름으로 APIMart를 통해 Vidu MoE, Vidu Q3 Pro, Vidu Q3 Turbo에 접근할 수 있습니다.
• 핵심 엔드포인트는 POST https://api.apimart.ai/v1/videos/generations입니다.
• 영상 작업은 비동기이므로, 먼저 task_id를 받은 다음 GET /v1/tasks/{task_id}를 폴링하거나 callback_url을 사용합니다.
• Vidu는 다음을 지원합니다:
  • 텍스트-투-비디오
  • 이미지-투-비디오
  • 레퍼런스 기반 영상
  • 첫-마지막 프레임 전환
• Q3 모델은 대사, 음향 효과, 음악 같은 내장 오디오를 더합니다.
• 클립은 최대 16초까지 실행될 수 있으며, 540p, 720p, 또는 1080p 출력을 지원합니다.
• 이 글의 APIMart 가격은 다음과 같이 명시합니다:
  • Q3 Pro: 720p에서 약 $0.12/초
  • Q3 Turbo: 720p에서 약 $0.048/초
• 출력 링크는 24시간 후 만료되므로, 성공 직후에 파일을 다운로드해야 합니다.

간단 비교

저에게 두드러지는 점은 전환이 얼마나 간단한지입니다: 대부분의 경우, 저는 그저 model 필드만 바꾸고 나머지 설정은 그대로 둡니다. 그래서 이 글은 설정 작업보다는 비용, 대기 시간, 그리고 출력 품질에 맞는 모델을 고르는 것에 더 가깝습니다.

Vidu 모델 설명: MoE 대 Q 시리즈

Vidu의 MoE 모델: 무엇이고 언제 사용하나

MoE (Mixture of Experts) 모델은 생성 작업의 서로 다른 부분을 모션, 장면 일관성, 프롬프트 제어를 위한 전문화된 익스퍼트에게 보냅니다. 일관성이 순수한 속도보다 더 중요한 멀티 신 또는 더 긴 프롬프트에 가장 합리적입니다.

다만 한 가지 함정이 있습니다. MoE는 더 많은 연산을 쓰고 Q 시리즈보다 처리 시간이 더 느립니다 ^[7]. 단순한 프롬프트에는 흔히 필요 이상입니다.

Vidu Q 시리즈와 Vidu Q3 Pro: 프로덕션 용도의 성능

MoE가 전문가라면, Q 시리즈는 프로덕션 작업을 위해 만들어진 옵션입니다. Vidu Q3 Pro는 다듬어진 시네마틱 출력과 스토리보드 기반 영상을 위해 설계되었습니다 ^[7]. 1080p 영상, 최대 16초 클립, 그리고 동기화된 대사와 음향 효과가 있는 오디오-비디오 생성을 지원합니다 ^[1][2][4]. APIMart에서 Q3 Pro는 초당 $0.12부터 시작합니다 ^[2][3].

Vidu Q3 Turbo는 더 빠른 장면 전환과 함께 속도와 더 낮은 비용 쪽으로 더 기웁니다 ^[6][7]. APIMart에서 Q3 Turbo는 초당 $0.048부터 시작합니다 ^[3].

워크플로에 맞춰 MoE와 Q 시리즈 중에서 선택하는 방법

이 선택은 대부분 프롬프트 복잡도, 처리 시간, 그리고 예산으로 귀결됩니다. 워크플로가 엄격한 지시 준수와 멀티 신 로직에 의존한다면, MoE를 선택하세요. 오디오-비주얼 동기화가 있는 다듬어진 출력이 필요하다면, Q3 Pro가 더 잘 맞습니다. 대안으로, Kling V3는 시네마틱 AI 영상을 위한 또 다른 고충실도 옵션을 제공합니다. 주된 목표가 빠른 반복이나 클립당 더 낮은 비용이라면, Q3 Turbo가 실용적인 선택입니다.

아래 표는 각 모델을 그것이 가장 잘 다루는 작업의 종류에 매핑합니다. 고급 옵션을 비교하는 분들을 위해, Sora 2는 동기화된 오디오와 함께 유사한 시네마틱 기능을 제공합니다.

다음으로, APIMart를 통해 모델을 선택하고, 인증하고, 요청을 보내는 방법을 살펴보세요.

APIMart를 통해 Vidu에 접근하는 방법

계정 설정, 인증, API 키 처리

모델을 고른 후에는, 하나의 API 키로 APIMart를 통해 작업을 보낼 수 있습니다. 먼저, APIMart 계정을 만들고 대시보드의 API 키 관리 페이지에서 키를 생성하세요 ^[2][3].

각 요청을 Authorization 헤더에 Bearer 토큰과 함께 보내세요:

Authorization: Bearer YOUR_API_KEY

저장의 경우, 키를 환경 변수나 AWS Secrets Manager 또는 GCP Secret Manager 같은 시크릿 매니저에 보관하세요. 개발, 스테이징, 프로덕션에 별도의 키를 사용하는 것도 도움이 됩니다. 키가 노출되면 즉시 교체하세요. 정해진 일정에 따라서도 동일하게 하세요. 그리고 요청을 로깅할 때는 task_id만 저장하세요 - 토큰 자체는 절대 저장하지 마세요 ^[5].

APIMart에서 Vidu 모델, 가격, 입력 스키마 찾기

로그인한 후에는, 아무것도 보내기 전에 카탈로그를 확인하세요. 그곳에서 모델 이름, 지원 입력, 그리고 현재 가격을 확인할 수 있습니다. APIMart의 카탈로그에서 Vidu 모델은 Video Generation 아래에 나열되어 있습니다. 같은 카테고리에서 MiniMax-Hailuo-02 같은 다른 고성능 모델도 찾을 수 있습니다. 그 페이지를 사용해 MoE, Q3 Pro, Q3 Turbo에 걸쳐 입력 스키마, 해상도, 그리고 초당 비용을 비교하세요 ^[2][3].

주의해서 볼 주요 필드는 다음과 같습니다:

• model
• prompt
• duration
• resolution
• aspect_ratio

텍스트-투-비디오 작업의 경우, aspect_ratio를 사용하세요. 이미지 기반 작업의 경우, 시스템이 대신 소스 이미지의 비율을 사용합니다 ^[2]. 텍스트 프롬프트는 2,000자로 제한됩니다 ^[2][3].

엔드포인트, 요청 구조, 비동기 작업 처리

모델을 선택한 후에는, 생성 요청을 제출하고 반환된 task_id로 비동기 작업을 추적하세요. https://api.apimart.ai/v1/videos/generations로 POST 요청을 보낸 다음, GET https://api.apimart.ai/v1/tasks/{task_id}로 작업 상태를 폴링하세요 ^[2][5].

작업은 다음 상태를 거칩니다:

• submitted
• queueing
• processing
• success 또는 failed

작업이 끝났을 때 APIMart가 앱에 알리기를 원한다면, callback_url을 추가하고 웹훅으로 결과를 받으세요 ^[5]. 작업이 success에 도달하면, 즉시 파일을 다운로드하세요. 거기서부터, 요청 필드를 텍스트-투-비디오 흐름이나 레퍼런스 기반 흐름 중 하나에 매핑할 수 있습니다.

텍스트-투-비디오와 레퍼런스 기반 영상을 위한 단계별 통합

모델 선택이 포함된 기본 텍스트-투-비디오 흐름

카탈로그에서 모델을 고른 후에는, 텍스트-투-비디오 흐름이 꽤 간단합니다. API 키를 서버 측에서 Authorization 헤더에 Bearer {your_api_key}로 보내세요.

다음은 viduq3-pro를 사용한 텍스트-투-비디오 작업을 위한 최소 페이로드입니다:

{
  "model": "viduq3-pro",
  "prompt": "A red fox running through a snowy forest at dusk, cinematic slow motion",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true
}

응답에는 task_id와 submitted, queueing, 또는 processing 같은 상태가 포함됩니다. 그 후에는, 반환된 task_id로 GET /v1/tasks/{task_id}를 폴링하거나, 요청에 callback_url을 전달해 작업이 success 또는 failed에 도달하면 플랫폼이 앱에 알리도록 할 수 있습니다 ^[1][7][10]. viduq3-turbo로 전환하고 싶다면, 대부분 model 필드만 바꾸면 됩니다.

비동기 패턴은 모드 전반에 걸쳐 동일하게 유지됩니다. 바뀌는 것은 입력 필드입니다.

이미지 또는 레퍼런스 입력 및 고급 제어 추가

이미지-투-비디오의 경우, image_urls 배열에 하나의 이미지 URL을 전달하세요. 텍스트-투-비디오에는 0개의 이미지, 이미지-투-비디오에는 1개, 첫-마지막 프레임 모드에는 2개를 사용하세요 ^[2]. 이미지 기반 모드에서는 출력 종횡비가 소스 이미지에서 오므로, aspect_ratio를 생략할 수 있습니다 ^[2]. URL을 사용하는 대신 파일을 직접 업로드한다면, 각 이미지를 PNG, JPEG, 또는 WebP 형식으로, 50 MB 미만으로 유지하고, 전체 HTTP 본문을 20 MB 미만으로 유지하세요 ^[9][8].

레퍼런스 기반 생성의 경우, subjects 배열과 함께 /reference2video 엔드포인트를 사용하세요. 각 subject를 name과 그 images로 정의한 다음, 프롬프트에서 @subjectname으로 호출하세요. Q3 모델은 subjects 기능에서 최대 7개의 레퍼런스 이미지 또는 텍스트 설명을 허용합니다 ^[6]. 첫-마지막 프레임 모드를 사용한다면, 실패를 줄이기 위해 두 이미지의 종횡비를 가깝게, 이상적으로는 0.8에서 1.25 비율 안으로 유지하세요 ^[8]. 얼굴이나 손이 관련될 때는, 왜곡 아티팩트를 줄이기 위해 모션 프롬프트를 미묘하게 유지하세요 ^[5].

아래 표는 두 흐름에 걸친 주요 파라미터를 보여줍니다:

여러 실행에 걸쳐 동일한 시각적 결과를 원한다면 테스트 중에 고정된 seed를 설정하세요 ^[2][9]. 급하지 않은 배치 작업의 경우, off_peak를 true로 설정하세요. 그러한 작업은 보통 48시간 이내에 완료되며 더 적은 크레딧을 사용합니다 ^[1][6].

사용량, 비용, 프로덕션 신뢰성 추적

요청이 작동하고 나면, 다음 작업은 프로덕션에서 비용과 신뢰성을 통제하에 유지하는 것입니다.

모든 요청에 대해 task_id와 타임스탬프를 로깅하세요. 그러면 민감한 자격 증명을 저장하지 않고도 안전하게 디버그할 수 있습니다 ^[5]. 큐 시간과 생성 시간을 별도로 추적하는 것도 도움이 되어, 플랫폼 지연과 모델 지연의 차이를 구분할 수 있습니다.

비용 추정의 경우, Vidu Q3 Pro는 720p에서 APIMart에서 초당 약 $0.12, Q3 Turbo는 초당 약 $0.048 비용이 듭니다 ^[3]. 지출이 통제를 벗어나지 않도록 월간 예산 상한의 50%, 80%, **100%**에 자동 알림을 설정하세요 ^[5].

재시도도 중요합니다. 5xx 에러에서는 지수 백오프를 사용하세요: 사용자에게 에러를 보여주기 전에 2초, 그다음 5초, 그다음 15초에 재시도하세요 ^[5]. Vidu Q3 시리즈 모델은 프로덕션 워크로드를 위한 99.9% SLA를 제공하지만 ^[3], 단기 실패는 여전히 발생하므로, 재시도는 어떤 배포 빌드에서든 일부가 되어야 합니다.

모델 선택 체크리스트와 핵심 요점

개발자, 크리에이터, 제품 팀을 위한 사용 사례 체크리스트

세 가지에 기반해 선택하세요: 프롬프트 복잡도, 속도, 그리고 출력 품질. 아래 표는 모델 비교를 실용적인 출시 선택으로 바꿔줍니다.

행을 골랐다면, 통합 섹션의 동일한 요청 스키마를 유지하세요. 쉽게 말하면: Q3 Turbo에서 아이디어를 시작한 다음, 최종 1080p 렌더를 Q3 Pro로 옮기세요. 간단한 워크플로이며, 필요 이상으로 쓰지 않고 빠르게 움직이도록 돕습니다.

모션 충실도가 가장 중요한 클립의 경우, 16초 최대치까지 늘리는 대신 5~10초를 목표로 하세요. 더 짧은 클립이 흔히 더 정밀한 모션과 더 적은 골칫거리를 줍니다.

출시 전에 기억해야 할 핵심 포인트

MoE는 복잡한 멀티 신 로직을 위한 선택입니다. Q3 Pro는 고충실도, 시네마틱 1080p 출력을 제공합니다 ^[3]. Q3 Turbo는 720p에서 $0.048/초의 저비용 옵션입니다 ^[3].

APIMart에서, 이 모델들 간의 전환은 단일 model 파라미터 변경에 불과합니다. 요청의 나머지 모든 것은 그대로 유지됩니다 ^[3]. 즉, 한 모델을 테스트하고, 다른 모델로 바꾸면서도, 통합 작업을 안정적으로 유지할 수 있습니다.

매번 동일한 비동기 흐름을 사용하세요:

• 요청 제출
• task_id 캡처
• 상태 폴링 또는 callback_url 사용

또한, 생성된 영상이 준비되면 곧바로 다운로드하세요. 출력 링크는 24시간 후 만료됩니다 ^[3][11].

자주 묻는 질문

어떤 Vidu 모델로 시작해야 하나요?

속도, 오디오, 시각 제어에 대한 필요에 맞는 모델로 시작하세요.

• viduq3-pro: 오디오-비주얼 동기화와 샷 분할에 최적
• viduq3-turbo: pro 버전보다 더 빠른 생성
• viduq1 또는 viduq2: 안정적인 영상 제작과 믿을 수 있는 카메라 움직임을 위한 견고한 선택

작업을 제출한 후 영상 작업을 어떻게 추적하나요?

영상 생성 작업을 두 가지 방법으로 추적할 수 있습니다.

프로덕션 용도로는, 초기 요청에 callback_url을 포함하는 것이 가장 좋은 옵션입니다. 그렇게 하면, Vidu API가 작업 업데이트와 결과 메타데이터를 사용자의 URL로 자동으로 곧바로 보냅니다. 즉, 직접 작업 상태를 계속 확인할 필요가 없습니다.

다른 옵션은 제출 후 받은 task_id로 상태 조회 API를 폴링하는 것입니다. 작업 상태가 success로 바뀌면, 응답에 영상 다운로드 URL과 기타 관련 메타데이터가 포함됩니다.

통합하기 전에 어떤 입력과 한도를 알아야 하나요?

Vidu API를 통합하기 전에, 입력이 다음 한도 안에 있는지 확인하세요:

• 이미지: PNG, JPEG, JPG, 또는 WebP만 가능; 각 파일은 50 MB 미만이고 최소 128×128 픽셀이어야 합니다
• 전체 HTTP 요청 본문: 최대 20 MB
• 텍스트 프롬프트: 최대 5,000자
• 페이로드 패스스루 데이터: 최대 1,048,576자

길이 한도는 사용하는 모델에 따라 다릅니다. Q3는 1~16초, Q2는 1~10초, Q1은 5초를 지원합니다.

또한, API 키를 안전하게 유지하세요. 클라이언트 측 코드에 노출하지 마세요. 대신 서버 측 중개자를 통해 요청을 보내세요.