Vidu MoE API 가이드： Mixture-of-Experts 비디오

한 줄로 요약하면： Vidu MoE 는 1~16초 클립, 최대 1080p, 24 fps, 비동기 전달, 그리고 한 요청에서의 선택적 오디오가 필요한 팀을 위한 숏폼 비디오 API입니다.

프로덕션 적합성을 판단한다면, 짧은 답은 이렇습니다. 비동기 작업을 처리할 수 있고, 재시도를 예산에 반영하고, 각 단계에 맞는 모델 티어를 고를 수 있을 때 가장 잘 작동합니다. 저라면 프리뷰에는 viduq3-turbo를, 최종 출력에는 viduq3-pro를 사용하겠습니다. 대부분의 작업은 720p에서 약 60~120초, 1080p에서 90~180초에 끝나며, 피크 대기 시간은 약 4분에 이릅니다.

가장 중요한 것은 다음과 같습니다.

• 입력 모드: 텍스트-투-비디오, 단일 이미지 애니메이션, Grok Imagine Video 대안, 2프레임 시작/끝 비디오, 멀티 이미지 레퍼런스 입력
• 클립 제한: 1초에서 16초
• 출력: 최대 1080p, 24 fps
• 오디오: 같은 요청에서 켤 수 있음
• 이미지 레퍼런스: 더 넓은 모델 기능 세트에서 최대 7개 이미지
• 주요 API 규칙: 이미지 URL을 보낸다면 aspect_ratio를 보내지 마세요
• 전달: task_id, 폴링, 또는 콜백을 통한 비동기
• 가격 예시: Pro는 5초에 약 $0.60, 12초에 $1.44
• 예산 현실: 승인된 클립당 2~3회 시도를 계획하세요

몇 가지 세부 사항이 두드러집니다. API는 model, prompt, 그리고 선택적 미디어 입력이 있는 간단한 JSON 요청을 사용합니다. 모델 선택은 간단합니다. _저비용 테스트에는 turbo, 고급 렌더에는 pro_입니다. Seed 제어는 재시도 전반에서 출력을 비슷한 방향으로 유지하는 데 도움이 되지만, 정확히 일치하지는 않습니다.

이것을 제품 팀에 평가한다면, 세 가지 질문에 집중하겠습니다.

1. 내 앱이 비동기 처리를 깔끔하게 다룰 수 있는가?
2. 프롬프트 전용 생성, 이미지 중심 제어, 또는 시작/끝 프레임 제어가 필요한가?
3. 첫 패스 비용뿐 아니라 재시도 후에도 예산이 여전히 유효한가?

빠른 비교

따라서 전체 가이드를 읽기 전 핵심은 간단합니다. Vidu MoE는 여러 입력 모드, 내장 오디오, 그리고 turbo와 pro 전환을 통한 비용 제어를 원하는 짧은 API 기반 비디오 생성에 잘 맞습니다. 나머지는 요청 설정, 상태 처리, 그리고 워크플로에 맞는 입력 방식을 고르는 일로 귀결됩니다.

Vidu MoE API 개요와 핵심 기능

API 수준에서 Vidu MoE는 작은 모델명, 워크플로, 출력 필드 세트에 매핑됩니다.

Vidu MoE는 API에서 균형 잡힌 Q3 모델인 viduq3-mix로 나타납니다. viduq3-turbo는 속도로 기울고, viduq3-pro는 더 많은 디테일로 기웁니다.

비디오 생성에서 Mixture-of-Experts가 의미하는 것

Mixture-of-experts는 생성 과정의 서로 다른 부분을 특화된 컴포넌트로 보냅니다. 실제로 이는 모션, 장면 구성, 프롬프트 준수에 도움이 됩니다.

Q3 시리즈는 지능형 장면 전환과 지능형 카메라 전환도 지원합니다 ^[2][4]. 멀티샷 시퀀스에서 가장 중요한데, 모델이 장면을 놓치면 연속성이 빠르게 무너질 수 있기 때문입니다.

지원 워크플로： 텍스트-투-비디오, 이미지-투-비디오, 레퍼런스 기반 생성

거기서부터 주요 차이는 보내는 입력 유형으로 귀결됩니다.

viduq3-mix는 네 가지 워크플로를 지원합니다.

• 프롬프트만으로 텍스트-투-비디오
• 하나의 시작 이미지로 이미지-투-비디오
• 외형과 스타일 일관성을 위한 1~7개 이미지로 레퍼런스-투-비디오
• 전환을 정의하는 두 프레임으로 시작-끝 비디오

프롬프트는 최대 5,000자를 지원합니다 ^[3][4]. viduq3-mix는 Subjects 엔티티 라이브러리를 지원하지 않습니다.

입력과 출력 한눈에 보기

각 작업은 task_id와 state를 반환하고, 최종 video_url은 처리 후에 사용 가능해집니다.

Q3 비디오는 24 fps로 실행되고, 1~16초 길이를 지원하며(Sora 2 기능과 비슷), 540p, 720p, 1080p 출력을 제공합니다 ^[2]. 이미지 입력은 파일당 50 MB로 제한됩니다 ^[4][1].

이러한 워크플로 옵션이 다음에 보낼 페이로드를 형성하며, 다음 섹션에서 이를 인증과 요청 형식으로 풀어냅니다.

인증, 요청 구조, APIMart 설정

Vidu MoE 비디오를 생성하려면 인증된 JSON 요청을 보내야 합니다. 요청 본문은 입력 모드에 따라 다릅니다. 텍스트 전용, 단일 이미지, 또는 멀티 이미지입니다.

API 자격 증명 받기와 요청 헤더 설정

APIMart API Key Management Page에서 API 키를 생성하세요 ^[6]. 이를 APIMART_API_KEY로 저장한 다음, 런타임에 Python에서는 os.environ.get("APIMART_API_KEY")로, Node.js에서는 process.env.APIMART_API_KEY로 로드하세요.

모든 요청에 다음 헤더를 포함하세요.

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json

비디오 생성 작업을 위한 최소 요청 페이로드

Vidu Q3 (MoE) 생성을 위한 표준 APIMart 엔드포인트는 https://api.apimart.ai/v1/videos/generations입니다 ^[6]. API는 image_urls로 모드를 파악합니다.

• 0개 URL = 텍스트-투-비디오
• 1개 URL = 이미지-투-비디오
• 2개 URL = 첫-마지막 프레임

핵심 필드와 사용 시점은 다음과 같습니다 ^[6].

여기서 쉬운 실수 하나가 있습니다. image_urls와 함께 aspect_ratio를 보내지 마세요. 이미지를 포함하면 API가 소스 이미지에서 화면 비율을 가져옵니다. 그래도 aspect_ratio를 보내면 요청이 400 오류를 반환합니다.

페이로드가 설정되면, 작업을 제출하고 결과를 폴링하기 시작할 수 있습니다.

예시 API 호출과 응답 패턴

텍스트-투-비디오 요청 예시:

curl -X POST https://api.apimart.ai/v1/videos/generations \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A product shot of a glass perfume bottle on a marble surface, camera slowly zooms in, soft studio lighting",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false
  }'

성공적인 제출은 task_id와 submitted 상태를 반환합니다 ^[6].

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_xxxxxxxxxx"
  }]
}

API는 비동기로 실행됩니다. 즉, 첫 응답은 작업이 접수되었다는 것만 알려줍니다. task_id를 사용해 "Get Task Status" 엔드포인트를 폴링하세요. 작업이 끝나면 응답에 MP4 링크가 포함되며, 보통 7일간 유효합니다 ^[6].

간단한 폴링 리듬이 잘 작동합니다.

• 처음 5분 동안 5초마다 폴링
• 그 이후에는 1분에 한 번 폴링
• 상태가 completed가 될 때까지 계속 폴링

그 시점에 반환된 비디오 링크를 다운로드해 저장하세요.

다음으로, 최종 비디오를 제어하기 위해 길이, 해상도, 화면 비율, 레퍼런스 입력을 조정하세요. 서로 다른 시네마틱 스타일이 필요한 프로젝트라면, 고급 비디오 생성을 위해 Kling V3 기능을 비교할 수도 있습니다.

생성 워크플로, 파라미터, 출력 제어

엔드 투 엔드 흐름： 제출, 모니터링, 가져오기, 결과 저장

작업을 제출한 후, 큰 프로덕션 결정은 간단합니다. 콜백을 사용하거나 상태를 폴링하는 것입니다. 대부분의 경우 프로덕션에는 callback_url이 더 나은 선택입니다. 폴링도 작동하지만, 백업 계획이어야 합니다. 콜백을 사용하면 API가 최종 상태를 엔드포인트로 보냅니다. 전달이 실패하면 최대 세 번 재시도합니다 ^[3].

작업은 그런 다음 고정된 상태 경로를 거칩니다. created → queueing → processing → success 또는 failed ^[3][4]. 작업이 failed에 도달하면 응답에 오류 코드가 포함됩니다. 그 코드를 기록하고 워크플로에서 처리해, 팀이 패턴을 발견하고 문제를 더 빨리 고칠 수 있도록 하세요.

상태가 success에 도달하면, 출력을 즉시 다운로드해 영구 스토리지에 저장하세요. API 호스팅 URL은 만료될 수 있으므로 그 단계가 중요합니다 ^[9].

구성, 모션, 길이, 일관성에 영향을 주는 핵심 파라미터

작업이 진행되면, 몇 가지 파라미터가 결과의 모습, 실행마다의 안정성, 소모하는 크레딧을 형성합니다.

처음부터 추적할 가치가 있는 파라미터 하나는 seed입니다. 마음에 드는 모션 패턴을 얻으면, 그 정수를 기록하고 보관하세요. 그러면 나중에 프롬프트를 조정할 때, 처음부터 다시 시작하는 대신 같은 seed를 재사용해 비슷한 전체 구성을 유지할 수 있습니다.

프롬프트만, 이미지 레퍼런스, 또는 둘 다를 사용할 때

이 입력 모드들은 속도와 제어를 맞바꾸게 해줍니다. 시각적 방향이 얼마나 확정되었는지에 맞는 것을 고르세요.

• 프롬프트 전용 (텍스트-투-비디오): 시각 에셋이 확정되기 전 초기 아이디어 구상, 스타일 테스트, 장면 실험에 가장 적합. 반복 비용을 낮추려면 540p나 720p에서 viduq3-turbo를 사용하거나, 고일관성 대안으로 WAN 2.6과 비교하세요 ^[7].
• 단일 이미지 (이미지-투-비디오): 제품 사진, 캐릭터 일러스트, 브랜드 비주얼처럼 특정한 것을 애니메이션화하고 싶을 때 가장 적합. 이커머스와 마케팅 작업에 강력하게 어울립니다.
• 이미지 두 개 (첫-마지막 프레임): 제품이 특정 각도로 도는 것이나 캐릭터가 정해진 포즈로 움직이는 것처럼, 전환이 설정된 결과에 도달해야 할 때 가장 적합 ^[5].

수동 프롬프팅이 고르지 않은 결과를 준다면, is_rec: true를 켜세요. API가 이미지로부터 최적화된 프롬프트를 생성해 프롬프트-이미지 정렬에 도움을 줄 수 있지만, 작업당 10 크레딧이 추가됩니다 ^[1].

성능, 가격, 실제 통합 시나리오

지연 시간, 신뢰성, 비디오당 비용 평가 방법

요청 형식을 확정한 후, 다음으로 볼 것은 속도, 가격, 작업 성공률입니다. 이것은 비동기 워크플로이므로, 앱은 작업을 제출하고, task_id를 저장하고, 나중에 폴링이나 콜백을 통해 최종 MP4를 가져와야 합니다 ^[3][6].

작업은 보통 간단한 경로를 거칩니다. 대기, 완료, 또는 실패입니다. 작업이 실패하면, 흔히 크레딧이 자동으로 환불됩니다 ^[3][10]. 이는 프로덕션에서 중요한데, 재시도가 예외적 경우가 아니라 과정의 일부이기 때문입니다.

처리 시간 측면에서, 720p 생성은 보통 60~120초에 끝납니다. 1080p의 경우 90~180초 정도를 예상하세요. 큐 시간은 오프피크 시간 동안 흔히 15~30초인 반면, 피크 p95 지연 시간은 약 4분까지 늘어날 수 있습니다 ^[7]. 그러니 그렇습니다, 프로덕션에서 잘 작동할 수 있습니다. 단, 시스템이 비동기 완료를 깔끔하게 처리하도록 만들어진 경우에만요.

가격에서, Pro 요율은 5초 클립을 $0.60에, 12초 클립을 $1.44에 둡니다 ^[10]. 실제로 대부분의 팀은 승인된 에셋당 2~3회 시도를 예산으로 잡아야 합니다. 그러면 쓸 만한 클립의 최종 비용이 길이에 따라 $1.20~$4.32 범위에 놓입니다 ^[10]. 테스트 모드라면, viduq3-turbo는 Pro의 약 절반 가격이며 빠른 반복에 더 합당합니다. Pro는 최종 렌더에 아껴두는 것이 좋습니다 ^[10].

이 수치는 기본 생성만 포함합니다. 재시도는 포함하지 않습니다. 팀이 여러 패스를 예상한다면, 그리고 대부분이 그렇습니다, 일상 프로덕션에 더 가까운 예산을 위해 합계에 2~3을 곱하세요.

사용 사례： 마케팅 비디오, 교육 클립, 이커머스 제품 비주얼

비용과 대기 시간이 명확해지면, 다음 단계는 배포할 에셋에 맞는 입력 모드를 고르는 것입니다. 최선의 선택은 대부분 한 가지로 귀결됩니다. 이미 얼마나 많은 시각적 제어를 가지고 있는가입니다.

이를 생각하는 간단한 방법은 이렇습니다.

• 브랜드 일관성이 중요하면 레퍼런스-투-비디오를 사용하세요
• 소스 이미지가 이미 좋아 보이면 이미지-투-비디오를 사용하세요
• 두 상태 사이의 모션이 필요하면 첫-마지막 프레임을 사용하세요
• 광고 변형을 빠르게 많이 원하면 텍스트-투-비디오를 사용하거나, 고일관성 전문 출력에는 MiniMax Hailuo 2.3을 고려하세요.

편집 시간을 줄이려는 팀에게는, 네이티브 오디오가 워크플로를 가장 크게 바꿉니다. 네이티브 오디오는 별도의 소싱과 편집 작업을 줄여주는데 ^[8], 한 번의 생성 패스로 완성된 클립을 원하는 팀에게는 추가 후반 작업 단계를 없앨 수 있습니다. 바로 그 지점에서 이 모델이 가장 유용해집니다. 긴 인계 체인으로 파일을 넘기지 않고도 배포 준비가 된 에셋에 가까워지는 것이 목표일 때입니다.

결론： Vidu MoE가 내 프로덕션 워크플로에 맞는지 결정하는 법

Vidu MoE는 최대 12~16초의 짧은 클립, 여러 입력 모드, 그리고 비동기 API 설정에서의 네이티브 오디오가 필요할 때 합당합니다. seed 파라미터는 반복 작업을 대략 같은 방향으로 유지하는 데 도움이 될 수 있지만, 동일한 입력이 비트 단위로 일치하는 출력을 낼 것이라 기대해서는 안 됩니다 ^[6][10]. 실패한 작업도 자동 크레딧 환불을 유발하는 경향이 있습니다 ^[3][10].

이는 대규모로 숏폼 비디오를 제작하고, 결과를 몇 분 기다릴 수 있으며, 재시도를 위한 예산 여유가 있는 팀에 맞습니다. 이것이 당신의 워크플로처럼 들린다면, APIMart는 마케팅 크리에이티브, 제품 비주얼, 설명 콘텐츠를 하나의 API 표면을 통해 실행하는 깔끔한 방법을 제공합니다.

FAQ

어떤 Vidu MoE 모델을 먼저 사용해야 하나요?

대부분의 개발자에게 viduq3-turbo가 시작하기 가장 좋은 곳입니다. 가장 빠른 생성 속도, 강력한 가성비, 그리고 오디오-비주얼 동기화와 지능형 장면 전환 같은 고급 기능을 제공합니다.

가장 완전한 기능 세트를 원한다면 viduq3-pro를 선택하세요. 스토리보드 생성과 최고 품질의 오디오-비주얼 정렬을 포함합니다. 두 모델 모두 1~16초 비디오와 최대 1080p 해상도를 지원합니다.

실패하거나 지연된 비디오 작업은 어떻게 처리해야 하나요?

비동기 워크플로에서 작업 ID를 사용하세요.

시간이 더 걸리는 작업의 경우, 상태 API를 가끔 폴링하거나 콜백 URL을 설정해 작업이 종료 상태에 도달했을 때 알림을 받으세요.

작업이 실패하면, 콜백이나 상태 응답에서 오류 세부 정보를 확인하세요.

프로덕션 안정성을 위해, 폴링할 때 지수 백오프를 사용해 요율 제한에 걸리지 않도록 하세요.

48시간을 넘겨 실행되는 오프피크 작업은 자동으로 취소되고, 포인트가 환불됩니다.

어떤 입력 모드가 가장 많은 제어를 제공하나요?

멀티 프레임 생성이 비디오가 한 순간에서 다음으로 어떻게 움직이는지에 대한 가장 많은 제어를 제공합니다. 하나의 프롬프트나 두 프레임 설정에 의존하는 대신, 최대 9개의 키 프레임 시퀀스를 설계할 수 있습니다.

그 추가 제어가 중요합니다. 각 전환마다 특정 이미지와 맞춤 프롬프트를 추가할 수 있어, 시각적 이야기가 프레임 단위로 원하는 경로를 따라갑니다.

이를 사용하려면, 이미지와 프롬프트를 image_settings 배열로 멀티프레임 엔드포인트에 보내세요.