seedance-2.0-mini

Seedance 2.0 Mini · API

POST https://kovapi.com/v1/videos/generations

Seedance 2.0 Mini 영상 생성(비동기)입니다. 엔트리 등급으로 사이트에서 초당 단가가 가장 낮습니다. 길이는 5~15초 사이의 정수, 해상도는 480P 또는 720P, 화면 비율은 5종이며 audio로 사운드트랙을 켜고 끕니다(기본값 true). 이미지-투-비디오는 image를 넣으세요. 작업 ID를 돌려주고(HTTP 202) GET /v1/videos/jobs/{id}를 폴링하면 됩니다. 초당 과금하며(참조 영상 길이도 포함) 실패 시 전액 환불합니다.

플레이그라운드에서 사용해 보기 →

인증

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

요청 본문

파라미터	타입	필수	설명
model	string	예	모델 ID. 여기서는 seedance-2.0-mini입니다.
prompt	string	예	영상의 내용, 카메라, 움직임을 설명하는 텍스트 프롬프트. 최대 5000 바이트(UTF-8. 한글 한 글자는 3바이트). 참조 이미지를 여러 장 넣을 때는 프롬프트에서 @Image1 / @Image2로 지칭할 수 있습니다. 예: "@Image1의 인물이 @Image2의 장면에 있다". 지칭하지 않으면 모델이 알아서 판단합니다.
duration	integer	아니오	길이(초). 5~15 사이의 정수이며 기본값은 5입니다. seconds로도 쓸 수 있습니다. 초당 과금합니다.
resolution	string	아니오	해상도: 480P / 720P(기본값 720P). 등급마다 단가가 다르니 모델 페이지의 요금표를 참고하세요.
size	string	아니오	화면 비율: 16:9 / 9:16 / 1:1 / 4:3 / 3:4(기본값 16:9). aspect_ratio로도 쓸 수 있습니다.
audio	boolean	아니오	결과 영상에는 항상 소리가 포함됩니다(대사·효과음·음악은 프롬프트로 생성). 끌 수 없으며 `false`를 보내도 효과가 없습니다.
image	string	아니오	참조 이미지 한 장(공개 URL, data: URI, base64). 인물·사물·장면·스타일 참조로 모델에 전달됩니다. 여러 장이면 images를 쓰세요. 이 모델에는 첫 프레임 지정이 없어 이미지가 영상의 첫 장면이 된다는 보장은 없습니다. 참조 소재가 하나도 없으면 텍스트-투-비디오입니다.
images	array	아니오	참조 이미지 여러 장. 이 모델은 최대 9장입니다. 각 항목은 공개 URL, data: URI, base64 모두 가능합니다. 상한을 넘으면 잘라내지 않고 거절합니다. reference_images로도 쓸 수 있습니다. 이미지마다 최대 16MB, jpg / png / webp / gif. 프롬프트에서 순서대로 @Image1, @Image2 … 로 지칭합니다.
image_role	string	아니오	생략 가능. 참조 이미지는 항상 참조(인물·장면·스타일)로 쓰이며 프롬프트에서 @Image1… 로 지칭합니다. 이 모델에는 첫 · 마지막 프레임 지정이 없습니다.
audio_reference	string / array	아니오	참조 오디오의 공개 http(s) 링크. 최대 3개이며 참조 이미지나 참조 영상과 함께 써야 합니다. audio_references로도 쓸 수 있습니다(둘을 동시에 보내지 마세요). base64(data:audio/mpeg;base64,...)도 됩니다. mp3 / wav / m4a. 프롬프트에서 @Audio1로 지칭합니다.
video_references	array	아니오	참조 영상. 최대 3개. 각 항목은 공개 http(s) 링크이거나, 로컬 영상을 base64로 직접 넣은 값(data:video/mp4;base64,..., mp4 / mov, 개당 최대 50MB)일 수 있으며, 저희가 호스팅한 뒤 업스트림에 전달합니다. 같은 요청에서 참조 이미지와 함께 쓸 수 있습니다(예: 사진으로 인물 외형, 영상으로 동작과 카메라 워크). 프롬프트에서 @Image1 / @Video1로 지칭하세요. 영상마다 최대 30초, 합계 최대 15초. 저희가 호스팅한 참조 소재는 7일간 보관됩니다.

요청 예시

cURL

# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "seedance-2.0-mini", "prompt": "a cat surfing a wave at sunset", "duration": 5, "resolution": "720P", "size": "16:9"}'
# with references: add "images": ["https://example.com/a.png"], "video_references": ["https://example.com/move.mp4"], "audio_reference": ["https://example.com/bgm.mp3"] and name them @Image1 / @Video1 / @Audio1 in the prompt
# 2) poll every ~5s until status=succeeded, then read data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

응답

200 · JSON

{
  "id": "img_3f9a...c2",
  "object": "video.generation.job",
  "status": "queued",
  "model": "seedance-2.0-mini"
}

비동기 영상 작업 (제출 → 폴링)

제출하면 즉시 HTTP 202와 작업 ID가 돌아옵니다. status=succeeded가 될 때까지 폴링한 뒤 data[0].url(mp4 링크)을 읽으세요. 지정할 수 있는 길이, 해상도, 화면 비율은 위 파라미터 표에 있으며, image 파라미터를 넣으면 이미지-투-비디오가 됩니다.

curl · 제출 (텍스트-투-비디오)

curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "seedance-2.0-mini", "prompt": "노을 속에서 서핑하는 고양이", "size": "16:9"}'

참조 소재 사용: images(참조 이미지), video_references(참조 영상), audio_reference(참조 오디오)를 한 요청에 함께 보낼 수 있으며 공개 URL, data: URI, base64 모두 됩니다. 프롬프트에서 @Image1 / @Video1 / @Audio1로 지칭하세요. 참조 이미지는 인물·장면·스타일을 정하며 첫 프레임으로 쓰이지 않습니다.

실제 인물의 얼굴도 가릴 필요 없이 참조 이미지로 사용할 수 있습니다. 이미지 속 인물의 초상을 사용할 권리가 있는지 반드시 확인해 주세요.

응답 예시

{ "id": "img_3f9a...c2", "object": "video.generation.job", "status": "queued", "model": "seedance-2.0-mini" }

curl · 폴링

curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

응답 예시

{
  "id": "img_3f9a...c2",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "seedance-2.0-mini",
  "data": [{ "url": "https://img.kovapi.com/i/9f86d081a8....mp4" }]
}

🕑 data[0].url은 저희 이미지 호스팅 링크로, 15일간 보관된 뒤 자동으로 삭제됩니다. 계속 쓰려면 다운로드해서 직접 운영하는 저장소나 CDN에 저장하세요.

초당 과금 ($0.046/초 × 길이). 예치 금액과 정산 금액이 정확히 일치하며, 실패하거나 시간이 초과된 렌더링은 자동으로 전액 환불됩니다.

폴링하고 싶지 않다면 작업을 제출할 때 callback_url을 추가하세요. 작업이 끝나면 결과를 서버로 보내 드립니다. 콘솔에서 기본 수신 주소를 설정할 수도 있습니다. 웹훅 문서 →

콘텐츠 요건

Seedance의 모든 작업은 콘텐츠 심사를 거칩니다. 대상은 프롬프트, 참조 소재, 생성된 영상이며 화면과 소리를 모두 심사합니다. 심사를 통과하지 못한 작업은 content_policy로 실패하며 과금되지 않습니다.

심사 시점

제출할 때 프롬프트와 참조 소재를 먼저 심사하고, 영상이 생성된 뒤 화면과 소리를 다시 심사합니다. 그래서 거절 결과는 제출 후 몇 초 만에 올 수도 있고 렌더링이 끝난 뒤에야 올 수도 있습니다(30분 넘게 걸릴 수도 있습니다). status가 failed, error.code가 content_policy로 끝난 작업은 심사에서 거절된 것입니다. Webhook을 쓰면 video.failed 이벤트가 전달됩니다.

과금 없음

거절된 작업은 과금되지 않습니다. 제출할 때 보류한 금액은 작업이 끝날 때 전액 환불되며, 호출 로그에도 과금되지 않은 것으로 표시됩니다.

소리

소리(대사, 내레이션, 노래, 효과음)는 모델이 프롬프트에 따라 생성하며 화면과 함께 심사합니다. 프롬프트에 쓴 대사, 내레이션, 가사는 실제로 읽히거나 노래로 불립니다. 목소리가 필요 없는 영상이라면 프롬프트에 대사와 가사를 쓰지 마세요. 이 모델은 항상 소리가 포함되며 끌 수 없습니다(audio: false를 보내도 효과가 없습니다). 업로드한 참조 오디오도 심사하며, 저작권이 있는 음악을 참조 오디오로 쓰면 거절될 수 있습니다. 소리가 심사를 통과하지 못하면 error.param이 audio가 되고, message에 생성된 소리인지 업로드한 참조 오디오인지 적혀 있습니다.

자주 거절되는 내용

성적 내용, 노출, 성적 암시(AI로 생성하거나 합성한 이미지 포함)
유혈, 잔혹한 묘사, 자해, 총상과 출혈 같은 폭력적 부상
총기, 폭발물, 마약
미성년자를 성적으로 다루는 내용은 일절 불가하며, 미성년자와 술·담배·마약·위험한 행동이 함께 나오는 장면도 거절됩니다
정치인, 연예인, 운동선수, 기업인 등 공인의 외모나 목소리(닮은 인물 포함)
혐오·차별 콘텐츠와 가짜 뉴스

긴 스토리보드 대본

위반 장면이 하나라도 있으면 영상 전체가 거절되며, 긴 스토리보드 대본에서 특히 자주 일어납니다. 액션 장면의 총격전이나 출혈 클로즈업, 미성년자가 술을 마시거나 담배를 피우는 장면이 있으면 전체가 실패합니다. 제출 전에 대본을 끝까지 읽고 이런 장면을 삭제하거나 고쳐 쓰세요.

실존 인물

실존 인물의 사진을 참조로 쓰려면 그 사람의 초상을 사용할 권리가 있어야 합니다. 모델별로 실존 인물 참조 이미지를 지원하는지는 이 페이지 위쪽에 적혀 있습니다.

거절된 뒤

같은 내용으로 다시 제출해도 다시 거절됩니다. 문제가 될 만한 부분을 찾아 프롬프트를 고쳐 쓰거나 참조 소재를 바꾼 뒤 다시 제출하세요.

오류 코드: content_policy · status: failed

오류 코드

모든 오류는 error.message / error.type / error.code / error.param 구조입니다. code로 판단하세요. 가장 자주 나오는 오류는 아래와 같으며, 전체 목록은 오류 코드에 있습니다.

HTTP	code	설명
401	invalid_api_key	키가 없거나, 유효하지 않거나, 정지된 키(`missing_api_key`, `invalid_api_key`).
402	insufficient_quota	잔액이 부족하거나 키가 예산 한도에 도달했습니다(`insufficient_quota`).
400	invalid_request	잘못된 파라미터 또는 없는 모델(`model_not_found` 등). `error.param`이 해당 필드를 알려 줍니다.
—	content_policy	콘텐츠 심사 불통과: 프롬프트, 참조 소재 또는 생성된 화면·소리가 위반으로 판정되었습니다. 과금되지 않습니다. 같은 내용은 다시 거절되므로 프롬프트를 고치거나 소재를 바꾸세요. 영상 작업은 `status`가 `failed`일 때 `error`에 담겨 반환됩니다.
429	rate_limit_exceeded	이 키에 설정한 분당 요청 수나 무료 모델의 하루 한도를 넘었거나, 이 모델이 가득 찼습니다(`rate_limit_exceeded`). `Retry-After`가 있으면 그 초만큼, 없으면 몇 초 기다린 뒤 다시 시도하세요.
502	upstream_*	업스트림 오류 또는 시간 초과로, 자동 재시도 후에도 실패했습니다. 이유는 `code`(`upstream_timeout`, `upstream_unavailable` 등)에 있습니다. 과금되지 않으니 다시 시도해도 됩니다.

전체 오류 코드 목록 →