여러 영상 생성 모델을 하나의 작업(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은 영구 보관용이 아니어서, 오래 쓸 영상은 자체 스토리지로 복사해야 합니다. 이건 모델 수와 상관없이 처음부터 넣어 두는 게 좋았습니다.
경계
이 방식은 "같은 요청이 모든 모델에서 동작한다"는 뜻이 아닙니다. 모델마다 다른 점은 그대로 두고, 그 차이를 실행 중에 이상한 결과로 만나는 대신 보내기 전에 드러내자는 것입니다. 생성 품질이나 처리 시간은 모델마다 직접 측정해야 합니다.
질문
여러 영상 모델을 쓰시는 분들은 모델별 파라미터 차이를 어디서 흡수하시나요?
- 위처럼 클라이언트 쪽 검증 테이블
- 서버가 400을 돌려주면 그 메시지를 그대로 노출
- 공통 파라미터로 추상화하고 내부에서 매핑
모델이 3~4개를 넘어가면 어느 쪽이 유지보수에 나았는지 경험을 듣고 싶습니다.
(참고: 정리한 서비스는 BeatAPI입니다. https://beatapi.io)