사용 가이드
Seedance 2.5 Flash 텍스트-투-비디오 연동 가이드: 파라미터, 초 단위 과금과 엔지니어링 실무
한 번의 요청에서 안정적인 출시까지: 파라미터 설정과 비용 계산
- 모델
- seedance-2.5-flash
이 페이지에서
이 모델이 하는 일
seedance-2.5-flash/text-to-video는 ByteDance의 텍스트-투-비디오 모델입니다. 텍스트 프롬프트를 입력하면 동기화된 오디오가 포함된 영상을 출력합니다. 입력 경로는 이 하나뿐이며, 이미지나 영상을 조건 입력으로 받지 않고 영상 이해도 하지 않습니다.
적합한 시나리오는 "한 문장으로 쓸 만한 짧은 영상 하나 만들기"입니다. 마케팅 소재 대량 생산, 제품 숏폼의 빈 화면과 분위기 컷, 콘텐츠 풀의 클립 채우기, 크리에이티브 방향의 빠른 시연 등이 여기에 해당합니다. 출발점이 이미지 한 장이라면 이미지-투-비디오 경로가 더 직접적이고, 참고 소재를 기준으로 주체의 일관성을 유지해야 한다면 참고 소재 기반 경로를 사용하세요.
요청에 어떤 파라미터가 있는가
- prompt(필수): 장면, 주체, 카메라 움직임과 동작. 최대 5000자.
- resolution:
480p또는720p, 기본값480p. - duration: 4에서 30 사이의 정수, 기본값 5, 단위는 초.
- aspect_ratio:
16:9,4:3,1:1,3:4,9:16,21:9,adaptive, 기본값adaptive(모델이 프롬프트에 따라 비율을 선택). - output_format:
mp4(기본값) 또는mov. - generate_audio: 기본값
true, 화면과 동기화된 대사, 효과음, 배경음을 생성합니다.
prompt 외에는 모두 기본값이 있으므로 최소 요청에는 prompt만 있으면 됩니다. 요청 본문은 엄격하게 검증됩니다. 선언되지 않은 필드를 추가로 보내면 조용히 무시되지 않고 거부됩니다. 덕분에 연동 단계의 오류가 과금 이후가 아니라 제출 시점에 드러납니다.
초 단위 과금 방식
과금 기준은 "초당 단가 × 출력 초수"이며 해상도 등급에 연동됩니다:
- 480p: $0.0679/초
- 720p: $0.1525/초
출력 초수는 요청의 duration을 그대로 사용하며 반올림으로 인한 예외 처리는 없습니다. 예를 들어 480p 5초는 $0.3395, 720p 5초는 $0.7625이며, 480p 30초는 $2.037, 720p 30초는 $4.575입니다. 길이가 두 배가 되면 비용도 두 배가 되며 "길수록 저렴해지는" 할인은 없습니다.
이는 세 가지를 의미합니다. 첫째, 예산 산정은 곱셈입니다. 먼저 건당 길이를 정하고 건수를 곱하세요. 둘째, 재시도는 곧 중복 과금입니다. 실패 재시도에는 반드시 상한을 두어야 합니다. 셋째, 장편은 한 번에 생성하지 말고 여러 개의 짧은 영상으로 나누어 각각 생성한 뒤 이어 붙이세요. 비용도 아끼고 실패가 망가진 구간에만 영향을 미치게 됩니다.
연동 형태: 비동기 작업
영상 생성은 시간이 오래 걸리는 작업이며 인터페이스는 비동기입니다. 제출 후 작업 식별자를 받고, 폴링하거나 콜백을 기다려 결과를 받은 뒤, 마지막으로 산출물을 다운로드하여 저장합니다. 이를 동기 RPC로 감싸 사용자 요청을 블로킹하지 마세요.
- 상태 머신 저장: 작업 식별자, 상태, 요청 파라미터를 데이터베이스에 저장하세요. 프로세스 메모리에만 두지 마세요. 재시작으로 작업을 잃는 것은 돈을 쓰고 결과를 못 받는 것과 같습니다.
- 폴링 백오프: 시작 간격은 짧게, 점차 늘리며 지터를 더하고, 동시에 작업마다 총 타임아웃을 설정해 무한 폴링 대신 타임아웃 시 실패 분기로 보내세요.
- 오류 분류: 파라미터 오류와 콘텐츠 위반은 확정적 실패이므로 재시도가 의미 없습니다. 네트워크 지터, 속도 제한 같은 일시적 오류만 백오프 재시도할 가치가 있습니다.
- 멱등성: 제출 측에 비즈니스 고유 키를 붙여 사용자가 중복 클릭으로 여러 작업과 중복 과금을 만들지 않도록 하세요.
프롬프트를 안정적으로 쓰는 방법
"주체 → 동작 순서 → 환경과 조명 → 카메라" 네 구간으로 나누어 쓰는 것이 형용사를 잔뜩 쌓는 것보다 훨씬 안정적입니다.
주체: 흰 고양이가 창턱에 앉아 있고, 역광
동작: 정지 상태에서 고개를 들어 창밖을 바라보며, 꼬리를 천천히 흔듦
환경과 조명: 오후의 따뜻한 빛, 얕은 심도, 조용한 실내 분위기
카메라: 미디엄 샷, 고정 카메라, 약간의 핸드헬드 느낌
세 가지 원칙이 있습니다. 하나의 프롬프트에는 연속된 한 장면만 담으세요. 여러 장면 전환을 한 번의 생성에 밀어 넣지 마세요. 프롬프트는 버전 관리하고 한 번에 변수 하나만 바꿔야 어느 변경이 효과를 냈는지 판단할 수 있습니다. 먼저 소량 샘플을 만든 뒤 대량으로 가세요. 아직 확정되지 않은 프롬프트를 대량으로 검증하지 마세요.
화면 비율과 카메라 언어는 자연어로 설명하면 됩니다. 모델에는 별도의 "카메라 무빙" 파라미터가 없으므로 존재하지 않는 필드를 기대하기보다 프롬프트에 적어 넣는 편이 더 신뢰할 수 있습니다.
출시 경로
- 파이프라인 통과: 대표 시나리오를 커버하는 프롬프트 세 개로 제출, 폴링, 다운로드가 모두 통과하는지 확인하세요. 효과가 좋은지는 우선 보지 마세요.
- 프롬프트와 길이 확정: 소수의 프롬프트를 고정하고 서로 다른 작성법과 서로 다른 길이의 산출물을 비교하며 각 건의 비용을 기록해 재사용 가능한 템플릿 라이브러리를 만드세요.
- 그레이스케일 확장: 비율에 따라 트래픽을 늘리며 성공률, 평균 소요 시간, 재시도율, 비용 곡선을 관찰하고 세 가지가 기준을 충족하면 더 늘리세요.
- 상시 운영: 주기적으로 템플릿 라이브러리를 점검하고, 비효율적인 작성법을 정리하며, 비용 추세와 재시도 임계값을 주시하세요.
모델 페이지에 최신 파라미터 설명과 가격이 있으니 연동 전에 한 번 대조하면 됩니다.