Seedance 2.5 | BeatAPI API Documentation

텍스트, 첫 프레임과 마지막 프레임, 또는 참조로 쓰는 최대 30장의 이미지·10개의 영상·10개의 오디오 클립으로 480p, 720p 또는 1080p의 4–30초 영상을 생성하고, 영상을 편집하거나 연장합니다.

비동기 방식: 생성 호출은 작업 ID를 반환하고, 작업이 성공하면 영상이 제공됩니다(보통 몇 분).
네 가지 입력 방식: 텍스트만, 첫 프레임, 첫 프레임과 마지막 프레임, 또는 참조 이미지·영상·오디오의 자유로운 조합(오디오만 보내도 됩니다).
task_type은 참조 영상이 새 영상의 소재인지, 편집할 영상인지, 연장할 영상인지를 지정하므로 결제 전에 요청을 검사할 수 있습니다.
소리는 기본적으로 추가 비용 없이 생성됩니다. 기본 형식은 MP4이며, 요청 시 MOV로 받을 수 있습니다.
영상의 크기와 길이, 그리고 참조 영상의 길이에 따라 과금됩니다. 실패한 작업은 비용이 들지 않습니다.

POST/v1/videos/tasks실행해 보기

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델 ID

Seedance 모델 네 개가 이 엔드포인트를 함께 씁니다. 아래 값은 게이트웨이 계약에서 그대로 가져왔으며, task_type, output_format, seed는 Seedance 2.5만 받습니다.

모델 ID	`duration` (s)	`resolution`	최대 참조 이미지 수	최대 참조 영상 수	최대 참조 오디오 수	이럴 때 선택하세요
`seedance-2.5`	4–30	`480p`, `720p`, `1080p`	30	10	10	최대 30초 클립, 많은 참조, 영상 편집·연장, 또는 MOV 출력이 필요한 경우.
`seedance-2`	4–15	`480p`, `720p`, `1080p`, `4k`	9	3	3	4K 출력이 필요하거나, 같은 해상도에서 2.5보다 낮은 가격을 원하는 경우.
`seedance-2-fast`	4–15	`480p`, `720p`	9	3	3	480p 또는 720p에서 `generate_audio`를 유지하면서 더 낮은 가격을 원하는 경우.
`seedance-2-mini`	4–15	`480p`, `720p`	9	3	3	가격이 가장 중요한 경우. 480p 또는 720p이며 `generate_audio` 필드는 없습니다.

엔드포인트와 인증

POST https://api.beatapi.io/v1/videos/tasks

`Authorization` string 필수

BeatAPI API 키를 Bearer <BEATAPI_API_KEY>로 보내세요. 키는 대시보드에서 만듭니다. 키는 서버에 보관하고, 브라우저나 모바일 앱에 포함하지 마세요.

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

작업 만들기

아래 파라미터를 엔드포인트로 POST하세요. 201은 작업이 접수되었고 가격만큼 잔액이 보류되었다는 뜻이며, 작업은 백그라운드에서 실행됩니다. data.id를 저장하세요.

완료 기다리기

status가 succeeded 또는 failed가 될 때까지 GET /v1/tasks/{task_id}를 호출하고, 호출 사이에 data.poll_after_seconds만큼 기다리세요(이미지 5초, 영상 8초). 또는 task.succeeded와 task.failed에 대한 웹훅을 등록하세요. 처리 시간 초과로 중단된 작업은 이벤트를 보내지 않으므로 폴링은 대비책으로 유지하세요.

결과 저장하기

succeeded이면 모든 data.output.media[].url을 다운로드해 필요한 파일을 저장하세요. BeatAPI는 결과 URL을 얼마 동안 사용할 수 있는지 보장하지 않습니다. failed이면 data.error_code와 data.error_message를 확인하세요. 보류된 금액은 잔액으로 돌아왔으며, data.retryable은 같은 요청을 다시 보내면 성공할 수 있는지 알려 줍니다.

입력 모드

모드	필수 입력	참고
텍스트로 영상 생성	`model`, `prompt`	미디어 배열을 보내지 않습니다.
첫 프레임	`model`, `prompt`, `images`(링크 1개)	이미지에서 영상이 시작되며 이미지의 화면비를 따릅니다.
첫 프레임과 마지막 프레임	`model`, `prompt`, `images`(링크 2개)	`images[0]`은 첫 프레임, `images[1]`은 마지막 프레임입니다.
참조	`model`, `prompt`, 그리고 `reference_images`, `reference_videos`, `reference_audios` 중 하나 이상	오디오만 보내는 것을 포함해 자유롭게 조합할 수 있습니다. `images`와 함께 쓸 수 없습니다. 참조 영상을 편집하거나 연장하려면 `task_type`을 사용하세요.

요청 파라미터

`model` string 필수

실행할 모델입니다.

값: seedance-2.5

값이 잘못된 경우

누락: "model" is required
이 엔드포인트에 이미지 모델을 보낸 경우: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

`prompt` string 필수

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일, 소리. 참조를 쓸 때는 각 입력의 용도를 적으세요.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
입력은 위치로 지칭하세요. 예: “첫 번째 참조 이미지”, “두 번째 참조 영상”.
참조 영상으로 새 영상을 만들 때는 “교체”, “제거”, “연장” 같은 단어를 피하세요. 모델이 편집 요청으로 해석할 수 있습니다. 확실히 하려면 task_type: "reference"를 보내세요. edit에는 무엇을 바꾸고 무엇을 유지할지, extend에는 다음에 일어날 일을 적으세요.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length

`images` string[] 선택

첫 프레임, 또는 첫 프레임과 마지막 프레임.

항목 수: 1–2
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

링크 하나: 이 이미지에서 영상이 시작됩니다. 링크 두 개: images[0]은 첫 프레임, images[1]은 마지막 프레임입니다.
영상은 첫 번째 이미지의 화면비를 따르며, aspect_ratio는 적용되지 않습니다.
사진이 더 많거나, 프레임이 아니라 영상을 안내할 사진이라면 대신 reference_images를 사용하세요.

값이 잘못된 경우

링크가 두 개 초과: "images" accepts at most 2 items
reference_* 필드와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL

`reference_images` string[] 선택

영상의 내용, 인물, 제품, 스타일을 안내하는 이미지입니다.

항목 수: 1–30
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

이미지는 목록 순서대로 사용되며, 프롬프트에서는 위치로 지칭하세요.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_images" accepts at most 30 items
images와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task

`reference_videos` string[] 선택

움직임, 카메라 워크, 내용을 가져올 영상, 또는 편집하거나 연장할 영상입니다(task_type 참고).

항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

각 링크는 바이트 범위 요청을 허용하는 호스트의 MP4 또는 MOV 파일이어야 합니다. 참조 영상 초 수가 과금되므로 게이트웨이가 작업 생성 전에 모든 클립의 길이를 읽습니다.
task_type edit과 extend에 필수입니다.

참조 영상은 재생되는 모든 초만큼 가격이 추가됩니다(과금 참고). 필요한 부분만 남도록 자르세요.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_videos" accepts at most 10 items
클립을 읽을 수 없습니다: A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.

`reference_audios` string[] 선택

따라 할 음악, 음성 또는 소리입니다. 이미지나 영상 참조 없이 오디오만 보내도 됩니다.

항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

WAV와 MP3 클립은 아래 제한에 따라 측정하며, 다른 형식은 측정 없이 모델에 전달합니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_audios" accepts at most 10 items

`duration` integer 선택기본값: `5`

영상 길이(초)이며 정수입니다.

기본값: 5
범위: 4–30

생략하면 5가 전송되며, task_type auto와 reference에서도 마찬가지입니다.
task_type: "extend"에서는 항상 보내세요. 원본을 포함한 완성 영상의 길이입니다. 5초 클립에 5초를 더하려면 10을 보내세요. 생략하면 총 5초를 요청하게 됩니다.
task_type: "edit"에서는 생략하세요. 결과는 원본 영상의 길이를 유지합니다.

값이 잘못된 경우

범위 밖이거나 정수가 아닌 경우: "duration" is outside its supported range
task_type: "edit"과 함께 보낸 경우: task_type "edit" keeps the reference video's length: leave "duration" out

`aspect_ratio` string 선택기본값: `adaptive`

가로:세로로 나타낸 영상 모양입니다. adaptive는 모델이 입력을 보고 고르게 합니다.

허용 값: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
기본값: adaptive

images에 첫 프레임이 있으면 무시되며, 영상은 프레임의 화면비를 따릅니다.
task_type edit 또는 extend에서는 생략하거나 adaptive를 보내세요. 결과는 원본 영상의 모양을 유지합니다.
adaptive(또는 프레임)를 쓰면 보류 금액은 선택한 해상도의 가장 큰 프레임을 기준으로 하므로 고정 비율보다 조금 높을 수 있습니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]
edit 또는 extend와 고정 비율을 함께 보낸 경우: task_type "edit" keeps the reference video's aspect ratio: leave "aspect_ratio" out or send "adaptive"

`resolution` string 선택기본값: `720p`

출력 해상도입니다. 해상도가 높을수록 초당 가격이 높습니다.

허용 값: 480p, 720p, 1080p
기본값: 720p

소문자만 허용됩니다. Seedance 2.5에서는 4K를 사용할 수 없습니다(seedance-2 사용).

값이 잘못된 경우

목록에 없는 값(예: 4k 또는 720P): "resolution" must be one of: [480p 720p 1080p]

`generate_audio` boolean 선택기본값: `true`

영상에 생성 사운드트랙을 넣을지 여부입니다. 가격은 어느 쪽이든 같습니다.

기본값: true

값이 잘못된 경우

true나 false가 아닌 경우: "generate_audio" must be a boolean

`seed` integer 선택

고정 값을 쓰면 결과를 재현하기 쉽습니다. 무작위 시드를 쓰려면 생략하거나 -1을 보내세요.

범위: -1–4294967295

같은 요청에 같은 시드를 쓰면 비슷한 결과가 나오지만, 완전히 같다고 보장되지는 않습니다.

값이 잘못된 경우

범위를 벗어난 경우: "seed" is outside its supported range

`task_type` string 선택

reference_videos로 무엇을 할지 지정합니다: 새 영상 만들기(reference), 편집(edit), 연장(extend). auto(또는 생략)는 프롬프트를 보고 모델이 결정합니다.

허용 값: auto, reference, edit, extend

종류를 지정하면 게이트웨이가 비용 청구 전에 요청을 검사할 수 있습니다. 종류별 규칙은 아래 작업 종류를 참고하세요.
auto 또는 reference에서는 항상 길이가 전송되므로(생략하면 5), 모델이 편집으로 해석하는 프롬프트는 제출 후 실패하거나(환불) 원본 영상 길이로 과금되는 편집으로 다시 실행됩니다. 편집이 목적이면 edit을 보내세요.

값이 잘못된 경우

목록에 없는 값: "task_type" must be one of: [auto reference edit extend]
참조 영상 없이 edit 또는 extend를 보낸 경우: task_type "edit" needs a video in "reference_videos"
참조 입력 없이 reference를 보낸 경우: task_type "reference" needs reference inputs

`output_format` string 선택

결과의 컨테이너 형식: mp4(생략 시 사용) 또는 mov. 가격은 같습니다.

허용 값: mp4, mov

mov는 추가 편집에 적합합니다. 항상 사용할 수 있는 것은 아니며, 사용할 수 없을 때는 비용 청구 전에 지금 쓸 수 있는 형식을 알려 주는 메시지와 함께 요청이 거부됩니다.

값이 잘못된 경우

목록에 없는 값: "output_format" must be one of: [mp4 mov]

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

images는 참조 입력과 함께 쓸 수 없습니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

미디어	작업 생성 전에 검사하는 제한
이미지	가로·세로 300–6000 px, 화면비(가로 ÷ 세로) 0.4–2.5, 각각 최대 30 MB
영상	각각 2–30초, 합계 30초, 가로·세로 300–6000 px, 화면비(가로 ÷ 세로) 0.4–2.5, 프레임당 407,696–8,295,044 픽셀(가로 × 세로), 24–60 FPS, 각각 최대 200 MB
오디오	각각 2–30초, 합계 30초, 각각 최대 15 MB

참조 영상은 바이트 범위 요청에 응답하는 호스트의 공개 HTTPS 링크에 있는 MP4 또는 MOV여야 합니다. 초 수가 과금되므로 길이를 읽을 수 없는 클립은 항상 거부됩니다.
이미지 크기는 호스트가 알려 줄 때 검사합니다. JPEG, PNG 또는 WebP를 사용하세요. 모델이 쓸 수 없는 파일은 제출 후 bad_request로 작업이 실패하며 환불됩니다.
제한은 길이, 변 길이, 화면비, 픽셀 수, 프레임 속도, 크기 순으로 보고됩니다. 메시지는 필드 오류와 마찬가지로 0부터 세어 목록과 위치로 입력을 명시합니다: reference_videos[0] is 1.5 seconds long; this model takes reference video of 2 to 30 seconds.
길이는 0.1초의 허용 오차로 측정합니다. 크기는 호스트가 알려 줄 때만 검사합니다.
이미지와 오디오 링크는 호스트가 4xx 오류로 응답하거나 빈 파일을 반환할 때만 작업 생성 시 거부됩니다(예: images[1] could not be downloaded: the URL returned HTTP 404.). 다른 문제는 제출 후에 드러납니다.
23.976 FPS 클립은 24 미만으로 간주되어 거부됩니다. 24 FPS 이상으로 다시 내보내세요.
로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

작업 종류

“필요” 열과 “생략” 열은 작업 생성 시 검사합니다. 이를 어긴 요청은 400 bad_request로 거부되며 비용이 들지 않습니다.

`task_type`	동작	필요	생략
`auto` 또는 생략	참조 영상이 소재인지, 편집할 영상인지, 연장할 영상인지를 프롬프트를 보고 모델이 결정합니다.	—	—
`reference`	참조로 만든 새 영상.	`reference_*` 입력 하나 이상	—
`edit`	참조 영상 하나를 변경합니다. 결과는 원본의 길이와 화면비를 유지합니다.	`reference_videos`	`duration`, `aspect_ratio`(또는 `adaptive` 전송)
`extend`	참조 영상 하나를 이어서 만들고 화면비를 유지합니다. `duration`은 원본을 포함한 전체 길이입니다.	`reference_videos`	`aspect_ratio`(또는 `adaptive` 전송)

다음 경우는 작업 생성 후에도 실패할 수 있습니다(bad_request, 환불): 원본 영상이 4초보다 짧거나 30초보다 긴 편집, 지정한 종류와 다른 작업으로 모델이 해석하는 프롬프트. 메시지는 어떤 task_type을 보낼지 또는 프롬프트를 어떻게 쓸지 등 바꿀 점을 알려 줍니다.

작업 종류별 프롬프트 작성법

필요한 것	보낼 값	프롬프트 작성 방식
참조로 만드는 새 영상	`task_type: "reference"`	새 샷을 설명하고 각 참조의 용도를 적으세요. “교체”, “제거”, “연장”, “이어서” 같은 표현은 피하세요.
영상을 변경하려면	`task_type: "edit"`	무엇을 추가·제거·교체할지, 무엇을 그대로 유지할지 적으세요.
영상을 이어서 만들려면	`task_type: "extend"`	다음에 일어날 일을 설명하고 `duration`을 전체 길이로 설정하세요.

이 모델이 받지 않는 필드

다음 필드를 보내면 무시되지 않고 과금 전에 거부됩니다.

watermark, quality, sound, multi_shots 또는 character_orientation → field "watermark" is not supported by model seedance-2.5(보낸 필드 명시).
BeatAPI 영상 모델에 없는 이름 → unknown field: <name>.
duration: -1(모델이 길이 선택) → "duration" is outside its supported range. 정수 초를 보내세요.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

텍스트로 영상 생성

720p 가로 5초 소리 있는 클립입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

첫 프레임과 마지막 프레임

첫 번째 이미지에서 두 번째 이미지로 이어지는 영상입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 6,
  "resolution": "720p"
}'

이미지와 오디오 참조

인물 이미지와 음악 클립을 따르는 퍼포먼스입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p",
  "task_type": "reference"
}'

이미지, 영상, 오디오 참조

영상 링크를 직접 준비한 MP4 또는 MOV로 바꾸세요. 참조 영상은 모든 초가 과금됩니다(과금 참고).

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video, cut to the beat of the reference music",
  "reference_images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p",
  "task_type": "reference"
}'

영상 편집

링크를 직접 준비한 4~30초의 MP4 또는 MOV로 바꾸세요. duration과 aspect_ratio는 생략하세요. 결과는 원본의 길이와 모양을 유지합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "Change the jacket of the person in the first reference video to bright red; keep everything else the same",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p",
  "task_type": "edit",
  "output_format": "mov"
}'

영상 연장

링크를 직접 준비한 클립으로 바꾸세요. 원본이 5초이면 duration: 10으로 5초가 추가됩니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The car keeps driving along the coast road as the sun sets, the camera rises to a wide aerial view",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "duration": 10,
  "resolution": "720p",
  "task_type": "extend"
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.939822,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.939822,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

필드	타입	설명
`data.id`	`string`	작업 ID: `task_` 뒤에 영문자와 숫자 32자가 붙습니다. 폴링과 웹훅 이벤트 매칭에 사용합니다.
`data.object`	`string`	항상 `task`.
`data.task_kind`	`string`	`image` 또는 `video`.
`data.capability_id`	`string`	보낸 모델 ID입니다.
`data.capability_version`	`integer`	모델의 계약 버전으로, 현재 `1`입니다.
`data.media_type`	`string`	`image` 또는 `video`.
`data.model`	`string`	보낸 모델 ID입니다(`capability_id`와 같음).
`data.status`	`string`	`queued`, `processing`, `succeeded` 또는 `failed`. 마지막 두 개만 최종 상태입니다.
`data.stage`	`string`	`status`와 같은 값으로, 오래된 클라이언트를 위해 유지합니다.
`data.created_at`	`integer`	작업 생성 시각(Unix 초)입니다.
`data.updated_at`	`integer`	마지막 변경 시각(Unix 초)입니다.
`data.completed_at`	`integer \| null`	작업 완료 시각(Unix 초)입니다. 실행 중에는 `null`입니다.
`data.poll_after_seconds`	`integer`	실행 중: 다음 폴링까지 기다릴 시간입니다(이미지 5, 영상 8).
`data.typical_seconds`	`object`	실행 중이며 최근 작업이 충분할 때: 최근 `window` 동안 `samples`개 작업의 `p50` 및 `p90` 완료 시간(초)입니다.
`data.output`	`object \| null`	결과입니다. `status`가 `succeeded`가 될 때까지 `null`입니다. 아래 출력 필드를 참고하세요.
`data.usage.credits_reserved`	`number`	작업 생성 시 잔액에서 보류한 USD 금액입니다.
`data.usage.credits_charged`	`number`	이 작업의 비용(USD)입니다. 실패한 작업에서는 `0`입니다.
`data.usage.credits_settled`	`number`	최종 청구 금액(USD)입니다. 작업이 성공하면 설정되고, 그렇지 않으면 `0`입니다.
`data.usage.credits_refunded`	`number`	잔액으로 환불된 금액(USD)입니다. 실패한 작업에서는 환불이 기록되면 보류 금액과 같아집니다.
`data.usage.billable_duration_seconds`	`integer`	영상만 해당: 가격 산정의 기준이 되는 초입니다. 모델이 길이를 보고하지 않으면 없습니다.
`data.request_id`	`string`	요청 ID입니다. 지원팀에 문의할 때 함께 알려 주세요.
`data.error_code`	`string \| null`	실패 코드입니다. 작업이 실패하지 않았다면 `null`입니다.
`data.error_message`	`string \| null`	무엇이 잘못되었고 무엇을 바꿔야 하는지 설명합니다. 작업이 실패하지 않았다면 `null`입니다.

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.939822,
      "credits_settled": 0.939822,
      "credits_refunded": 0,
      "credits_charged": 0.939822,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

필드	타입	설명
`output.media`	`object[]`	생성된 파일입니다. 이 모델은 영상 하나를 만듭니다.
`output.media[].type`	`string`	항상 `video`.
`output.media[].url`	`string`	저장된 영상의 HTTPS 링크입니다. 내려받아 보관하세요. 보관 기간은 보장하지 않습니다.
`output.media[].mime_type`	`string`	`video/mp4`, 또는 `output_format: "mov"`에는 `video/quicktime`.
`output.r2_url`	`string`	이전 클라이언트를 위해 다시 넣은 영상 URL입니다. 대신 `media`를 읽으세요.

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.939822,
      "credits_settled": 0,
      "credits_refunded": 0.939822,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

필드	타입	설명
`data.error_code`	`string`	`bad_request`, `content_policy_violation`(요청 수정 필요) 또는 `processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`(나중에 재시도) 중 하나입니다. 오류를 참고하세요.
`data.error_message`	`string`	문제와 해결 방법을 설명하는 문장입니다.
`data.retryable`	`boolean`	실패한 작업에만 있습니다. 같은 요청을 다시 보내면 성공할 수 있을 때 `true`입니다.
`data.usage`	`object`	환불이 기록되면(보통 작업이 실패하는 시점): `credits_charged`와 `credits_settled`는 `0`이고, `credits_refunded`는 `credits_reserved`와 같습니다.

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

가격은 영상의 크기와 길이에 따라 정해집니다. 초 수가 많을수록, 해상도가 높을수록, 프레임이 클수록 비쌉니다. 소리와 output_format은 가격에 영향을 주지 않으며, 참조 이미지와 오디오는 추가 비용이 없습니다.
참조 영상 없이 16:9 클립은 초당 약 $0.096(480p),$ 0.186(720p), $0.461(1080p)입니다. 다른 화면비는 몇 퍼센트 차이가 납니다.
reference_videos를 쓰면 요청 전체가 더 낮은 “영상 입력 포함” 요금으로 바뀌며, 참조 영상의 모든 초가 출력 초처럼 계산됩니다. 16:9 기준 출력과 참조 합계 초당 약 $0.058(480p),$ 0.112(720p), $0.276(1080p)입니다.
아래 표는 8초 클립 기준이며, “영상 입력 포함” 행에는 8초 참조 영상이 포함됩니다.
편집은 원본 영상 비용을 두 번 지불합니다. 한 번은 참조로, 한 번은 원본 길이(정수 초로 올림)를 유지하는 출력으로 과금됩니다. usage.billable_duration_seconds에 출력 초 수가 표시됩니다.
가격은 작업 생성 시 보류됩니다. adaptive 또는 프레임을 쓰면 보류 금액은 해당 해상도의 가장 큰 프레임을 기준으로 합니다. 보류 금액을 지불하며, 제공된 영상의 실제 금액이 더 크면 실제 금액을 지불합니다.
아주 짧은 참조 영상은 최소 길이로 과금될 수 있어 정산 금액이 보류 금액보다 커질 수 있습니다. 완료된 작업의 usage에 청구 금액이 표시됩니다.
실패한 작업은 제출 후 콘텐츠 검수에서 거부된 경우를 포함해 전액 환불됩니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

옵션	정가(USD)
8초 · 480p · 영상 입력 없음	$0.774512
8초 · 480p · 영상 입력 포함	$0.927006
8초 · 720p · 영상 입력 없음	$1.499055
8초 · 720p · 영상 입력 포함	$1.794205
8초 · 1080p · 영상 입력 없음	$3.710161
8초 · 1080p · 영상 입력 포함	$4.421435

자주 발생하는 오류

오류 또는 증상	원인	해결 방법
400 `resolution "1080p" is not available for this model right now; available: …`	현재 이 모델을 제공하는 라인 중 그 값을 받는 곳이 없습니다. `aspect_ratio`에서도 같은 일이 생길 수 있습니다.	목록에 있는 값을 사용하거나 나중에 다시 시도하세요.
400 `field "watermark" is not supported by model seedance-2.5`	이 모델이 받지 않는 필드입니다(`quality`, `sound`도 마찬가지).	해당 필드를 삭제하세요.
400 `"resolution" must be one of: [480p 720p 1080p]`	`4k`, `2k` 또는 `720P` 같은 대문자.	`480p`, `720p` 또는 `1080p`를 보내세요. 4K는 `seedance-2`를 사용하세요.
400 `"duration" is outside its supported range`	범위 안의 정수가 아니거나 문자열로 보냈습니다.	`5` 같은 정수를 보내세요.
400 `Cannot combine "images" with reference inputs in one task`	같은 요청에 프레임과 `reference_*`가 있습니다.	프레임과 참조 중 하나를 사용하세요. 사진이 여러 장이면 모두 `reference_images`에 넣으세요.
400 `task_type "edit" keeps the reference video's length: leave "duration" out`	편집에 `duration`을 보냈습니다.	`duration`을 삭제하세요.
400 `A reference video could not be read: reference_videos[0]: …`	MP4나 MOV가 아니거나, 바이트 범위를 지원하지 않는 호스트이거나, 404이거나, 빈 파일입니다.	범위 요청을 지원하는 공개 HTTPS 스토리지에 클립을 올리거나 `POST /v1/files`로 업로드하세요.
400 `The reference videos run 35 seconds in total; this model takes at most 30.`	참조 클립의 합계가 너무 깁니다.	클립을 자르거나 삭제하세요.
`bad_request`가 있는 작업 `failed`: “Seedance read the prompt as an edit of the reference video …”	편집처럼 들리는 프롬프트와 `auto`: 길이는 항상 전송되며(기본값 5), 편집은 원본의 길이를 유지합니다.	`duration`과 `aspect_ratio` 없이 `task_type: "edit"`을 보내거나, 새 샷을 설명하는 프롬프트와 함께 `task_type: "reference"`를 보내세요.
`bad_request`가 있는 작업 `failed`: “For task_type “edit”, the video being edited must be 4 to 30 seconds long …”	편집 원본 영상이 4초보다 짧거나 30초보다 깁니다.	원본을 자르거나 교체하세요. 실패한 작업은 환불되었습니다.
작업이 `content_policy_violation`과 함께 `failed`	프롬프트, 입력 또는 결과가 콘텐츠 검수에서 거부되었습니다(실존 인물, 공인, 저작권 있는 캐릭터). 실존 인물이 나오는 입력은 거부될 수 있으며, 얼굴을 승인받는 방법은 없습니다.	입력을 바꾸세요. 그대로 재시도하면 다시 실패하며, 비용은 청구되지 않습니다.
402 `insufficient_credits`	잔액이 보류 금액보다 적습니다. 긴 참조 영상과 `adaptive`는 보류 금액을 높입니다.	충전하거나, 참조를 줄이거나, 고정 `aspect_ratio`를 선택하세요.

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

HTTP 상태	`error.code`	조치
400	`bad_request`, `content_policy_violation`	요청을 수정하세요. 메시지에 해당 필드가 표시됩니다. 그대로 재시도하지 마세요.
401	`missing_api_key`, `invalid_api_key`(오래된 클라이언트에서는 `unauthorized`가 보일 수 있음)	유효한 키를 `Authorization: Bearer <key>`로 보내세요.
402	`insufficient_credits`	충전하거나 키 한도를 올린 뒤 다시 보내세요.
403	`forbidden`	이 키나 계정으로는 이 모델을 사용할 수 없습니다(예: 무료 크레딧은 일부 모델만 지원). 그대로 재시도하지 마세요.
404	`not_found`	`GET /v1/tasks/{task_id}`에서: 이 키의 계정에 해당 작업이 없습니다. ID를 확인하세요.
409	`idempotency_conflict`	새 `Idempotency-Key`를 사용하거나, 이 키를 쓴 첫 요청이 끝날 때까지 기다리세요.
429	`rate_limit_exceeded`	`Retry-After`에 표시된 시간(또는 `error.retry_after_seconds`초)만큼 기다린 뒤 재시도하세요.
500	`internal_error`	백오프를 적용해 재시도하고, 계속되면 `request_id`와 함께 지원팀에 문의하세요.
503	`processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`	과금되지 않았습니다. 지수 백오프를 적용해 재시도하세요.

Seedance 2.0과의 차이

	Seedance 2.5	Seedance 2.0, 2.0 Fast, 2.0 Mini
최대 영상 길이	30 s	15 s
참조 구성	이미지 최대 30장, 영상 10개, 오디오 클립 10개	이미지 최대 9장, 영상 3개, 오디오 클립 3개
참조 영상 길이	각각 2–30초, 합계 30초	각각 1.8–15초, 합계 15초
오디오만 참조	허용	거부: 이미지나 영상 참조가 하나 이상 필요
`task_type`(편집, 연장)	예	아니요
`output_format`(MOV)	예	아니요(MP4)
`seed`	예	아니요
4K	아니요	`seedance-2`만

인증

AuthorizationBearer

API 키를 Authorization: Bearer <BEATAPI_API_KEY>로 보내세요.

헤더

Idempotency-Keystring선택 사항<=255 characters

요청

This endpoint expects an object.

modelenum필수

실행할 모델입니다.

값: seedance-2.5

값이 잘못된 경우

누락: "model" is required
이 엔드포인트에 이미지 모델을 보낸 경우: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

허용된 값:

promptstring필수1-5000 characters

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일, 소리. 참조를 쓸 때는 각 입력의 용도를 적으세요.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
입력은 위치로 지칭하세요. 예: “첫 번째 참조 이미지”, “두 번째 참조 영상”.
참조 영상으로 새 영상을 만들 때는 “교체”, “제거”, “연장” 같은 단어를 피하세요. 모델이 편집 요청으로 해석할 수 있습니다. 확실히 하려면 task_type: "reference"를 보내세요. edit에는 무엇을 바꾸고 무엇을 유지할지, extend에는 다음에 일어날 일을 적으세요.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length

aspect_ratioenum선택 사항기본값 adaptive

가로:세로로 나타낸 영상 모양입니다. adaptive는 모델이 입력을 보고 고르게 합니다.

허용 값: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16

기본값: adaptive

images에 첫 프레임이 있으면 무시되며, 영상은 프레임의 화면비를 따릅니다.
task_type edit 또는 extend에서는 생략하거나 adaptive를 보내세요. 결과는 원본 영상의 모양을 유지합니다.
adaptive(또는 프레임)를 쓰면 보류 금액은 선택한 해상도의 가장 큰 프레임을 기준으로 하므로 고정 비율보다 조금 높을 수 있습니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]
edit 또는 extend와 고정 비율을 함께 보낸 경우: task_type "edit" keeps the reference video's aspect ratio: leave "aspect_ratio" out or send "adaptive"

durationinteger선택 사항4-30기본값 5

영상 길이(초)이며 정수입니다.

기본값: 5

범위: 4–30

생략하면 5가 전송되며, task_type auto와 reference에서도 마찬가지입니다.
task_type: "extend"에서는 항상 보내세요. 원본을 포함한 완성 영상의 길이입니다. 5초 클립에 5초를 더하려면 10을 보내세요. 생략하면 총 5초를 요청하게 됩니다.
task_type: "edit"에서는 생략하세요. 결과는 원본 영상의 길이를 유지합니다.

값이 잘못된 경우

범위 밖이거나 정수가 아닌 경우: "duration" is outside its supported range
task_type: "edit"과 함께 보낸 경우: task_type "edit" keeps the reference video's length: leave "duration" out

generate_audioboolean선택 사항기본값 true

영상에 생성 사운드트랙을 넣을지 여부입니다. 가격은 어느 쪽이든 같습니다.

기본값: true

값이 잘못된 경우

true나 false가 아닌 경우: "generate_audio" must be a boolean

imageslist of strings선택 사항

첫 프레임, 또는 첫 프레임과 마지막 프레임.

항목 수: 1–2

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

링크 하나: 이 이미지에서 영상이 시작됩니다. 링크 두 개: images[0]은 첫 프레임, images[1]은 마지막 프레임입니다.
영상은 첫 번째 이미지의 화면비를 따르며, aspect_ratio는 적용되지 않습니다.
사진이 더 많거나, 프레임이 아니라 영상을 안내할 사진이라면 대신 reference_images를 사용하세요.

값이 잘못된 경우

링크가 두 개 초과: "images" accepts at most 2 items
reference_* 필드와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL

output_formatenum선택 사항

결과의 컨테이너 형식: mp4(생략 시 사용) 또는 mov. 가격은 같습니다.

허용 값: mp4, mov

mov는 추가 편집에 적합합니다. 항상 사용할 수 있는 것은 아니며, 사용할 수 없을 때는 비용 청구 전에 지금 쓸 수 있는 형식을 알려 주는 메시지와 함께 요청이 거부됩니다.

값이 잘못된 경우

목록에 없는 값: "output_format" must be one of: [mp4 mov]

허용된 값:

reference_audioslist of strings선택 사항

따라 할 음악, 음성 또는 소리입니다. 이미지나 영상 참조 없이 오디오만 보내도 됩니다.

항목 수: 1–10

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

WAV와 MP3 클립은 아래 제한에 따라 측정하며, 다른 형식은 측정 없이 모델에 전달합니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_audios" accepts at most 10 items

reference_imageslist of strings선택 사항

영상의 내용, 인물, 제품, 스타일을 안내하는 이미지입니다.

항목 수: 1–30

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

이미지는 목록 순서대로 사용되며, 프롬프트에서는 위치로 지칭하세요.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_images" accepts at most 30 items
images와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task

reference_videoslist of strings선택 사항

움직임, 카메라 워크, 내용을 가져올 영상, 또는 편집하거나 연장할 영상입니다(task_type 참고).

항목 수: 1–10

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

각 링크는 바이트 범위 요청을 허용하는 호스트의 MP4 또는 MOV 파일이어야 합니다. 참조 영상 초 수가 과금되므로 게이트웨이가 작업 생성 전에 모든 클립의 길이를 읽습니다.
task_type edit과 extend에 필수입니다.

참고: 참조 영상은 재생되는 모든 초만큼 가격이 추가됩니다(과금 참고). 필요한 부분만 남도록 자르세요.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_videos" accepts at most 10 items
클립을 읽을 수 없습니다: A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.

resolutionenum선택 사항기본값 720p

출력 해상도입니다. 해상도가 높을수록 초당 가격이 높습니다.

허용 값: 480p, 720p, 1080p

기본값: 720p

소문자만 허용됩니다. Seedance 2.5에서는 4K를 사용할 수 없습니다(seedance-2 사용).

값이 잘못된 경우

목록에 없는 값(예: 4k 또는 720P): "resolution" must be one of: [480p 720p 1080p]

허용된 값:

seedinteger선택 사항-1-4294967295

고정 값을 쓰면 결과를 재현하기 쉽습니다. 무작위 시드를 쓰려면 생략하거나 -1을 보내세요.

범위: -1–4294967295

같은 요청에 같은 시드를 쓰면 비슷한 결과가 나오지만, 완전히 같다고 보장되지는 않습니다.

값이 잘못된 경우

범위를 벗어난 경우: "seed" is outside its supported range

task_typeenum선택 사항

reference_videos로 무엇을 할지 지정합니다: 새 영상 만들기(reference), 편집(edit), 연장(extend). auto(또는 생략)는 프롬프트를 보고 모델이 결정합니다.

허용 값: auto, reference, edit, extend

종류를 지정하면 게이트웨이가 비용 청구 전에 요청을 검사할 수 있습니다. 종류별 규칙은 아래 작업 종류를 참고하세요.
auto 또는 reference에서는 항상 길이가 전송되므로(생략하면 5), 모델이 편집으로 해석하는 프롬프트는 제출 후 실패하거나(환불) 원본 영상 길이로 과금되는 편집으로 다시 실행됩니다. 편집이 목적이면 edit을 보내세요.

값이 잘못된 경우

목록에 없는 값: "task_type" must be one of: [auto reference edit extend]
참조 영상 없이 edit 또는 extend를 보낸 경우: task_type "edit" needs a video in "reference_videos"
참조 입력 없이 reference를 보낸 경우: task_type "reference" needs reference inputs

허용된 값:

응답

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

오류

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

모델 ID

엔드포인트와 인증

Authorization string 필수

요청 처리 방식

작업 만들기

완료 기다리기

결과 저장하기

입력 모드

요청 파라미터

model string 필수

prompt string 필수

images string[] 선택

reference_images string[] 선택

reference_videos string[] 선택

reference_audios string[] 선택

duration integer 선택기본값: 5

aspect_ratio string 선택기본값: adaptive

resolution string 선택기본값: 720p

generate_audio boolean 선택기본값: true

seed integer 선택

task_type string 선택

output_format string 선택

입력 미디어 제한

작업 종류

작업 종류별 프롬프트 작성법

이 모델이 받지 않는 필드

요청 예시

텍스트로 영상 생성

첫 프레임과 마지막 프레임

이미지와 오디오 참조

이미지, 영상, 오디오 참조

영상 편집

영상 연장

응답

작업 생성(201)

완료된 작업

출력 필드

실패한 작업

전체 예시

과금

자주 발생하는 오류

HTTP 오류 요약

Seedance 2.0과의 차이

인증

헤더

요청

응답

오류

`Authorization` string 필수

`model` string 필수

`prompt` string 필수

`images` string[] 선택

`reference_images` string[] 선택

`reference_videos` string[] 선택

`reference_audios` string[] 선택

`duration` integer 선택기본값: `5`

`aspect_ratio` string 선택기본값: `adaptive`

`resolution` string 선택기본값: `720p`

`generate_audio` boolean 선택기본값: `true`

`seed` integer 선택

`task_type` string 선택

`output_format` string 선택