← 목록으로

Show GN: 두 번째 영상 모델을 붙일 때 확인한 것들 (Seedance 2 → MiniMax H3)

요약
  • 여러 영상 생성 모델을 하나의 작업 API로 통합할 때 발생하는 모델별 입력 규격, 작업 상태, 결과 형식의 차이를 표준화하는 방법을 설명합니다.
  • 특히 모델별 허용 해상도와 화면비 등을 사전에 검증하는 시스템을 구축하여 실행 중 발생할 수 있는 오류를 방지하는 것이 핵심입니다.

여러 영상 생성 모델을 하나의 작업(task) API로 묶는 서비스를 만들고 있습니다. Seedance 2 다음으로 MiniMax H3를 붙이면서 "모델 이름만 바꾸면 되겠지"라는 생각이 틀린 지점을 정리해 봤습니다. 두 번째 영상 모델을 연동하시는 분들께 체크리스트로 쓰이면 좋겠습니다.

1. 입력 규격: 같은 이름, 다른 값

두 모델 모두 prompt, duration(4~15초), aspect_ratio, resolution을 받습니다. 하지만 값이 다릅니다.

항목 Seedance 2 MiniMax H3
해상도 480p 720p 1080p 4K (기본 720p) 768P 2K (기본 768P)
화면비 기본값 adaptive 텍스트 모드는 16:9, adaptive 불가
첫/끝 프레임 images reference_*와 같이 못 씀 같음. 프레임 모드는 항상 adaptive
참조 이미지 + 고해상도 reference_images가 있으면 1080p 불가 reference_videos는 768P, 2K에서만
오디오 generate_audio (기본 true) 별도 플래그 없음

720p를 그대로 H3에 보내면 당연히 거절됩니다. 그래서 모델별 허용값을 한곳에 모아 두고, 보내기 전에 검증하도록 했습니다.

type Spec = { resolutions: string[]; textAspect: string[]; rejectWithReferenceImages?: string[]; }; const SPECS: Record<string, Spec> = { "seedance-2": { resolutions: ["480p", "720p", "1080p", "4K"], textAspect: ["adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], rejectWithReferenceImages: ["1080p"], }, "minimax-h3": { resolutions: ["768P", "2K"], textAspect: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], }, }; export function validate(req: { model: string; resolution?: string; aspect_ratio?: string; images?: string[]; reference_images?: string[]; }) { const spec = SPECS[req.model]; if (!spec) return `unknown model: ${req.model}`; if (req.resolution && !spec.resolutions.includes(req.resolution)) return `${req.model} does not accept resolution ${req.resolution}`; if (req.images?.length && req.reference_images?.length) return "images (first/last frame) cannot be combined with reference_*"; const textMode = !req.images?.length && !req.reference_images?.length; if (textMode && req.aspect_ratio && !spec.textAspect.includes(req.aspect_ratio)) return `${req.model} text mode does not accept aspect_ratio ${req.aspect_ratio}`; if (req.reference_images?.length && spec.rejectWithReferenceImages?.includes(req.resolution ?? "")) return `${req.model} cannot use ${req.resolution} with reference_images`; return null; }

해상도를 "720p ≈ 768P"처럼 자동으로 바꿔 주는 것도 생각했지만 하지 않았습니다. 가격과 결과물이 달라지기 때문에, 조용히 바꾸기보다 보내기 전에 명확한 에러를 주는 쪽이 낫다고 판단했습니다.

2. 작업 상태: 공개 상태는 4개로 고정

업스트림마다 상태 이름이 다를 수 있습니다. 앱 코드에 그 이름이 새어 나가면 모델을 추가할 때마다 분기가 늘어납니다. 그래서 공개 상태는 queued, processing, succeeded, failed 네 개로 고정하고, 변환은 연결 계층 안에서만 합니다.

앱은 모델과 상관없이 똑같이 처리합니다.

  • POST /v1/videos/tasks로 작업을 만들고 data.id를 저장
  • GET /v1/tasks/{task_id}를 5~10초 간격(무작위 지연 포함)으로 조회
  • succeeded 또는 failed에서 멈춤

3. 결과 형식: output.media[] 하나로

완성 영상은 모델과 관계없이 data.output.media[]에 type, url, mime_type으로 들어옵니다. 다만 URL은 영구 보관용이 아니어서, 오래 쓸 영상은 자체 스토리지로 복사해야 합니다. 이건 모델 수와 상관없이 처음부터 넣어 두는 게 좋았습니다.

경계

이 방식은 "같은 요청이 모든 모델에서 동작한다"는 뜻이 아닙니다. 모델마다 다른 점은 그대로 두고, 그 차이를 실행 중에 이상한 결과로 만나는 대신 보내기 전에 드러내자는 것입니다. 생성 품질이나 처리 시간은 모델마다 직접 측정해야 합니다.

질문

여러 영상 모델을 쓰시는 분들은 모델별 파라미터 차이를 어디서 흡수하시나요?

  1. 위처럼 클라이언트 쪽 검증 테이블
  2. 서버가 400을 돌려주면 그 메시지를 그대로 노출
  3. 공통 파라미터로 추상화하고 내부에서 매핑

모델이 3~4개를 넘어가면 어느 쪽이 유지보수에 나았는지 경험을 듣고 싶습니다.

(참고: 정리한 서비스는 BeatAPI입니다. https://beatapi.io)

그냥 목록으로
원문 보기 ↗