메인 콘텐츠로 건너뛰기
POST

인증

Authorization
string
header
필수

##모든 API는 Bearer Token 인증이 필요합니다##

API Key 얻기:

API Key 관리 페이지에서 API Key를 받으세요

요청 헤더에 다음을 추가하세요:

본문

application/json
model
enum<string>
기본값:seedance-2.5-text-to-video
필수

비디오 생성 모델 이름

사용 가능한 옵션:
seedance-2.5-text-to-video
예시:

"seedance-2.5-text-to-video"

prompt
string
필수

생성할 비디오를 설명하는 텍스트 프롬프트. 중국어와 영어를 지원하며, 중국어는 500자 이내, 영어는 1000단어 이내를 권장합니다. 프롬프트 최대 길이: 10000 tokens

주의:

  • 이 모델은 순수 텍스트-비디오 모델로, image_urls, video_urls, audio_urls 입력을 지원하지 않습니다
예시:

"A macro lens focuses on a green glass frog on a leaf. The focus gradually shifts from its smooth skin to its completely transparent abdomen, where a bright red heart is beating powerfully and rhythmically."

duration
integer
기본값:5

비디오 길이(초), 기본값은 5초

설명:

  • 4~30초 사이의 임의의 정수값을 지원합니다
  • -1: 자동 길이. 모델이 4–30초 범위에서 결정하며 실제 출력 길이에 따라 과금됩니다
  • 재생 시간은 과금에 직접적으로 영향을 미칩니다
예시:

8

quality
enum<string>
기본값:720p

비디오 해상도, 기본값은 720p

선택 가능한 값:

  • 480p: 낮은 해상도, 낮은 가격
  • 720p: 표준 해상도, 기본값
  • 1080p: 초고해상도

초안 모드: draft가 true이면 480p만 사용할 수 있으며, 생략해도 자동으로 480p가 적용됩니다

사용 가능한 옵션:
480p,
720p,
1080p
예시:

"720p"

draft
boolean
기본값:false

초안 모드 활성화 여부로, 기본값은 false입니다

설명:

  • true: 먼저 480p 초안 비디오를 생성합니다. 더 빠르게 생성되며 일반 480p 요금이 적용됩니다
  • 활성화 시 quality는 480p로 지정하거나 생략해야 합니다. 다른 해상도를 전달하면 400 파라미터 오류가 반환됩니다
  • 요청 본문의 최상위에만 지정할 수 있습니다. model_params 안에 지정하면 400 파라미터 오류가 반환됩니다

최종 비디오로 변환:

  • 초안이 완료되면 작업 조회 응답에 draft_expires_at이 반환됩니다
  • 이 시각 이전에 Seedance 2.5 Draft-to-Video에 초안의 작업 ID를 전달하면 동일한 내용의 1080p 최종 비디오를 생성할 수 있습니다
  • 최종 비디오와 초안은 별도로 과금됩니다. 초안이 만족스럽지 않다면 변환하지 않고 초안 요금만 지불할 수 있습니다
  • 기본 유효기간은 초안 완료 후 24시간이며, 실제 기한은 draft_expires_at을 기준으로 합니다. 대기 중에 유효기간이 만료되어도 변환에 실패하므로 변환 요청을 미리 제출하세요

일시적으로 사용할 수 없는 경우: 서비스를 일시적으로 사용할 수 없으면 503이 반환될 수 있습니다. 오류 코드가 draft_unavailable이면 나중에 다시 시도하거나 draft를 제거하고 일반 모드로 생성하세요

예시:

false

aspect_ratio
enum<string>
기본값:adaptive

비디오 화면 비율, 기본값은 adaptive

선택 가능한 값:

  • 16:9(가로), 9:16(세로), 1:1(정사각형), 4:3, 3:4, 21:9(울트라와이드)
  • adaptive: 모델이 프롬프트에 따라 최적의 화면 비율을 자동 선택

각 해상도별 픽셀 값:

사용 가능한 옵션:
16:9,
9:16,
1:1,
4:3,
3:4,
21:9,
adaptive
예시:

"16:9"

generate_audio
boolean
기본값:true

동기화된 오디오 생성 여부, 기본값은 true

선택 가능한 값:

  • true: 비디오에 동기화된 오디오(음성, 효과음, 배경 음악)가 포함되며, 추가 요금이 없습니다. 오디오 생성 효과를 최적화하려면 대화 부분을 큰따옴표로 감싸는 것을 권장합니다
  • false: 무음 비디오 출력
예시:

true

content_filter
boolean
기본값:true

콘텐츠 필터, 기본값은 true

선택 가능한 값:

  • true: 표준 콘텐츠 안전 검사, 기본값입니다
  • false: 콘텐츠 제한을 완화하며 +10%(1.1x)가 청구됩니다. 불법 및 금지된 콘텐츠는 이 설정과 관계없이 항상 적용됩니다

웹 검색과 함께 사용할 수 없음:

  • content_filter: false와 model_params.web_search: true는 동시에 사용할 수 없으며, 함께 전달하면 400 파라미터 오류가 반환됩니다
  • 웹 검색이 필요한 경우 content_filter: true(기본값)를 유지하세요
예시:

true

output_format
enum<string>
기본값:mp4

출력 컨테이너 형식, 기본값은 mp4

선택 가능한 값:

  • mp4: H.264 인코딩으로 호환성이 가장 좋고 표준 색상 정밀도를 제공하며, 기본값입니다
  • mov: H.264 + yuv444p 크로마 서브샘플링 + PCM 오디오로 색 재현력이 높아 색보정·키잉·합성 등 후반 작업에 적합합니다. 브라우저 내 재생이 지원되지 않을 수 있으므로 다운로드 후 VLC / mpv / ffplay로 재생하세요. 추가 요금 없음
사용 가능한 옵션:
mp4,
mov
예시:

"mp4"

model_params
object

모델 확장 파라미터

callback_url
string<uri>

작업 완료 후 HTTPS 콜백 주소

콜백 시점:

  • 작업 완료(completed) 또는 실패(failed) 시 트리거
  • 과금 확인 완료 후 전송

보안 제한:

  • HTTPS 프로토콜만 지원
  • 내부 네트워크 IP 주소로의 콜백 금지(127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x 등)
  • URL 길이는 2048자를 초과할 수 없습니다

콜백 메커니즘:

  • 타임아웃: 10초
  • 실패 시 최대 3회 재시도(실패 후 각각 1/2/4초 후 재시도)
  • 콜백 응답 본문 형식은 작업 조회 API 반환 형식과 동일
  • 2xx 상태 코드를 성공으로 간주하며, 다른 상태 코드는 재시도를 트리거합니다
예시:

"https://your-domain.com/webhooks/video-task-completed"

응답

비디오 생성 작업이 성공적으로 생성되었습니다

created
integer

작업 생성 타임스탬프

예시:

1761313744

id
string

작업 ID

예시:

"task-unified-1774857405-abc123"

model
string

실제 사용된 모델 이름

예시:

"seedance-2.5-text-to-video"

object
enum<string>

작업의 구체적 유형

사용 가능한 옵션:
video.generation.task
progress
integer

작업 진행률 (0-100)

필수 범위: 0 <= x <= 100
예시:

0

status
enum<string>

작업 상태

사용 가능한 옵션:
pending,
processing,
completed,
failed
예시:

"pending"

task_info
object

비디오 작업 상세 정보

type
enum<string>

작업의 출력 유형

사용 가능한 옵션:
text,
image,
audio,
video
예시:

"video"

usage
object

사용량 및 과금 정보