seedance-2.0-fast

Seedance 2.0 Fast · API

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

Seedance 2.0 Fast 영상 생성 API입니다. Seedance 2.0의 고속 버전으로 생성이 더 빠르며, 초 단위로 과금됩니다. 5~15초, 480P / 720P, 화면 비율 5종을 지원합니다. 참조 이미지, 참조 영상, 참조 오디오를 한 요청에 함께 넣을 수 있으며 모든 영상에 소리가 포함됩니다. 비동기 작업이며 실패하면 과금되지 않습니다.

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

빠른 시작

세 단계면 됩니다: 작업 제출 → 결과 조회 → 영상 링크 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다.

1단계 · 제출(작업 ID를 바로 돌려줍니다, HTTP 202)

curl

curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.0-fast", "prompt": "비 오는 밤 네온 불빛의 거리, 고인 빗물을 따라 떠내려가는 종이배, 낮은 앵글로 뒤따르는 카메라, 선명한 물보라와 물에 비친 반영", "duration": 5, "resolution": "720P", "size": "16:9"}'

응답(HTTP 202)

JSON

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedance-2.0-fast"
}

2단계 · status가 succeeded 또는 failed가 될 때까지 5~10초마다 조회

curl

curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"

성공했을 때의 응답

JSON

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedance-2.0-fast",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.0-fast"}
}

3단계 · data[0].url이 결과 영상(MP4)입니다. 15일 동안 보관되므로 더 오래 쓰려면 내 저장소에 내려받아 두세요.

전체 예제(Python: 제출 → 대기 → 로컬에 저장)

Python

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 제출
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "seedance-2.0-fast",
    "prompt": "비 오는 밤 네온 불빛의 거리, 고인 빗물을 따라 떠내려가는 종이배, 낮은 앵글로 뒤따르는 카메라, 선명한 물보라와 물에 비친 반영",
    "duration": 5,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 10초마다 조회, 최대 1시간까지 대기
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 영상 내려받기
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedance-2.0-fast.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])

대기 중일 때는 조회 결과에 queue_position(앞에 있는 작업 수)과 eta_seconds(예상 대기 시간)도 함께 옵니다. 프로그램에 정해 둔 대기 시간을 넘겨도 다시 제출하지 마세요. 작업은 그대로 남아 있으니 나중에 같은 작업 ID로 이어서 조회하면 됩니다.

인증

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

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

사양 한눈에 보기

길이	5–15초
해상도	480P / 720P
화면 비율	16:9 / 9:16 / 1:1 / 4:3 / 3:4
참조 이미지	최대 9장 · 참조로 사용(인물, 장면, 스타일), 프레임으로는 쓰지 않음
참조 영상	최대 3개, 합계 15초 이내
참조 오디오	최대 3개, 각 15초 이하
소리	항상 포함(대사·효과음·음악은 모델이 생성), 끌 수 없음
프롬프트 길이	최대 5,000바이트(UTF-8, 한자 약 1,666자)
과금 방식	초 단위: 초당 단가 × (결과 영상 초 수 + 참조 영상 초 수)

요청 파라미터

POST /v1/videos/generations의 요청 본문(JSON):

파라미터	타입	필수	설명
model	string	예	모델 ID: `seedance-2.0-fast`.
prompt	string	예	영상의 내용(화면, 카메라 움직임, 동작)을 설명합니다. 최대 5,000바이트입니다(UTF-8 기준, 한자 1자가 3바이트이므로 약 1,666자).
duration	integer	아니오	길이(초): 5~15 사이의 정수이며, 생략하면 5입니다. `seconds`로 써도 됩니다.
resolution	string	아니오	해상도: 480P / 720P 중 하나이며, 생략하면 720P입니다. P를 붙여 주세요(`720`처럼 P가 없으면 거절됩니다).
size	string	아니오	화면 비율: 16:9 / 9:16 / 1:1 / 4:3 / 3:4 중 하나이며, 생략하면 16:9입니다. `aspect_ratio`로 써도 됩니다.
images	array	아니오	참조 이미지, 최대 9장. 인물, 장면, 스타일을 정하는 데 쓰이며 프레임으로는 쓰이지 않습니다. 프롬프트에서는 보낸 순서대로 `@Image1`, `@Image2`로 지칭하세요. 한 장뿐이면 `image`에 넣어도 됩니다.
video_references	array	아니오	참조 영상, 최대 3개, 합계 15초 이내. 참조 이미지와 함께 보낼 수 있으며(사진으로 외모를, 영상으로 동작과 카메라 움직임을 정함), 프롬프트에서는 `@Video1`처럼 지칭하세요. 각 영상은 공개 URL 또는 `data:video/mp4;base64,...`로 보낼 수 있습니다(mp4 / mov, 개당 50MB 이하, 요청 전체 100MB 이하). 링크는 파일 자체를 바로 내려받을 수 있어야 합니다. YouTube, Bilibili, TikTok, 클라우드 드라이브 공유 페이지 같은 웹 페이지 링크는 제출 시 400으로 거부됩니다.
audio_reference	array	아니오	참조 오디오, 최대 3개, 각각 15초 이하(실제 길이로 판정하므로 15.1초도 거부됩니다). 공개 http(s) URL로 보내며, 참조 이미지나 참조 영상과 함께 보내야 합니다. 프롬프트에서는 `@Audio1`처럼 지칭하세요. 링크는 파일 자체를 바로 내려받을 수 있어야 합니다. YouTube, Bilibili, TikTok, 클라우드 드라이브 공유 페이지 같은 웹 페이지 링크는 제출 시 400으로 거부됩니다.
audio	boolean	아니오	결과 영상에는 항상 소리가 포함됩니다(대사·효과음·음악은 모델이 프롬프트에 따라 생성). 끌 수 없으며 `false`를 보내도 효과가 없습니다.
callback_url	string	아니오	작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요.
n	integer	아니오	작업 하나는 영상 1개를 만들므로 넣지 않아도 됩니다. 1보다 큰 값을 넣어도 영상은 1개만 나오지만, 제출할 때 n개 분의 크레딧이 예약되고 초과분은 작업이 끝날 때 돌아옵니다.

그 밖의 필드(seed, negative_prompt, fps, watermark 등)는 전달되지 않으며 가격에도 영향을 주지 않습니다. 결과는 항상 MP4이며 url로 돌려줍니다.

가격

초 단위로 과금합니다: 비용 = 선택한 해상도의 초당 단가 × (결과 영상 초 수 + 모든 참조 영상의 초 수). 참조 이미지와 참조 오디오는 무료입니다. 제출할 때 예약되고, 실패하면 전액 환불됩니다. 1크레딧 = $0.005.

해상도	초당 크레딧	초당 가격(USD)	5초 영상 1개
480P	9.2	$0.046	$0.23
720P	15	$0.075	$0.375

참조 소재

참조 이미지는 최대 9장이며 인물, 장면, 제품, 스타일을 정합니다. Seedance는 이미지를 프레임으로 쓰지 않습니다. 이미지 속 인물이나 사물을 영상에 등장시키려면 프롬프트에서 그 이미지를 지칭하세요(@Image1, @Image2 …, 보낸 순서대로 번호가 붙음).
참조 영상은 최대 3개(합계 15초 이내)이며 동작, 카메라 움직임, 리듬을 정합니다. 참조 오디오는 최대 3개(각각 15초 이하, 15.1초도 거부됩니다)이며 말하는 목소리나 음악을 정하고, 참조 이미지나 참조 영상과 함께 보내야 합니다. 세 가지 소재를 한 요청에 함께 넣을 수 있으며, 각각 @Image1 / @Video1 / @Audio1로 지칭합니다.
실제 인물의 얼굴도 가릴 필요 없이 참조 이미지로 사용할 수 있습니다. 이미지 속 인물의 초상을 사용할 권리가 있는지 반드시 확인해 주세요.
이미지는 각각 공개 이미지 URL, data: URI, base64 중 하나로 보낼 수 있으며 한 장당 16MB 이하입니다. 여러 장은 images에 배열로 넣으세요. 제출할 때 당사가 이미지를 먼저 저장한 뒤 작업을 대기열에 넣습니다. 읽을 수 없는 이미지가 있으면 400으로 거절되고 message에 몇 번째 이미지인지 적혀 있으며, 과금되지 않습니다.
당사가 저장한 참조 소재는 7일, 결과 영상은 15일 동안 보관됩니다.

참조 이미지와 참조 영상 함께 쓰기

curl

curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.0-fast", "prompt": "@Image1 속 소녀가 @Image2 속 거리에서 @Video1 속 춤을 춘다", "images": ["https://example.com/character.png", "https://example.com/street.png"], "video_references": ["https://example.com/dance.mp4"], "duration": 5, "size": "16:9"}'

@Image1은 첫 번째 참조 이미지, @Video1은 첫 번째 참조 영상입니다. 참조 영상은 과금되지 않으며 결과 영상의 길이만 과금됩니다.

콘텐츠 요건

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

심사 시점

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

과금 없음

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

소리

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

자주 거절되는 내용

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

긴 스토리보드 대본

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

실존 인물

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

거절된 뒤

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

오류 코드: content_policy · status: failed

작업 상태와 응답 필드

GET /v1/videos/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 5~10초마다 조회하거나, 아래의 웹훅으로 결과를 받으세요. 조회는 무료이며, 같은 계정의 어느 키로든 조회할 수 있습니다.

상태	의미
queued	대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다.
processing	생성 중.
succeeded	완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다.
failed	실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다.

processing이 queued로 돌아갈 때가 있습니다. 예를 들어 서비스가 붐빌 때, 완성된 영상을 다시 가져오는 중일 때, 서비스가 재시작된 뒤입니다. 작업을 끝내지 못하면 게이트웨이가 자동으로 다시 만들 수 있습니다. 몇 번을 재시도하든 작업 하나에 한 번만 과금됩니다.
한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 영상 링크는 15일 동안 보관됩니다.

생성 시간

보통 2~4분 걸립니다.

오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.

제출할 때 돌아오는 오류

HTTP	code	원인	조치
400	invalid_request	파라미터가 올바르지 않습니다. 길이, 해상도, 화면 비율 또는 참조 소재 수가 이 모델의 허용 범위를 벗어났거나, 프롬프트가 너무 길거나, 참조 이미지나 참조 영상을 읽을 수 없거나, 항상 소리가 포함되는 모델에 `audio: false`를 보낸 경우 등입니다. 구체적인 원인은 `message`에 적혀 있습니다.	`message`에 적힌 대로 고친 뒤 다시 제출하세요.
400	invalid_callback_url	`callback_url`이 공개된 http(s) 주소가 아니거나 2000자를 넘습니다.	인터넷에서 접근할 수 있는 주소를 쓰세요.
400	model_not_found	모델 ID의 철자가 틀렸거나, `model`이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우).	`GET /v1/models` 또는 API 레퍼런스에 있는 모델 ID를 쓰세요.
401	invalid_api_key	키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다.	콘솔의 「API Keys」 페이지에서 이 키를 확인하세요.
402	insufficient_quota	이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다.	동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요.
429	rate_limit_exceeded	이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다.	몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요.
503	model_maintenance	모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다.	점검이 끝나면 다시 시도하세요. 진행 상황은 서비스 상태에서 볼 수 있습니다.
503	service_unavailable	참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. 작업은 만들어지지 않았고 과금되지도 않았습니다.	잠시 후 다시 시도하세요.

작업 실패(`status`가 `failed`)

code	언제 나오나요	조치
content_policy	영상: 프롬프트, 참조 소재, 또는 생성된 화면이나 소리가 콘텐츠 심사를 통과하지 못했습니다(소리가 걸렸으면 `param`이 `audio`입니다). Wan Standard 및 Prime: 입력 소재가 심사를 통과하지 못했습니다. `error.reason`은 `FaceDetectionSuspect`(실제 사람 얼굴 의심) 또는 `DataInspectionFailed`(입력 콘텐츠 심사 실패)입니다. `error.message`에 원인과 조정 방법이 표시됩니다. 실패한 작업은 과금되지 않습니다.	프롬프트를 고쳐 쓰거나 참조 소재를 바꾼 뒤 다시 제출하세요. 같은 입력은 다시 거부됩니다.
render_failed	영상: 이번에는 영상이 나오지 않았습니다. 대개 일시적인 현상입니다.	같은 요청을 그대로 다시 제출하면 대개 성공합니다.
invalid_material	영상: 업스트림이 입력 소재에 문제가 있다고 판단했습니다. 포괄적인 오류이며 일시적인 경우가 많습니다.	먼저 그대로 다시 제출해 보세요. 계속 나오면 참조 소재와 프롬프트 길이를 확인하세요.
duration_rejected	영상: 길이가 받아들여지지 않았습니다. 대부분 참조 오디오나 참조 영상이 상한을 넘은 경우이며, 1초가 안 되게 넘어도 마찬가지입니다.	참조 오디오나 참조 영상을 상한 이내로 잘라서 다시 제출하세요. 같은 입력은 다시 실패합니다.
reference_unreadable	영상: 모델이 참조 이미지, 영상 또는 오디오를 내려받지 못했습니다. 대부분 YouTube나 클라우드 드라이브 공유 페이지 같은 웹 페이지 링크인 경우입니다.	파일을 바로 내려받을 수 있는 링크로 바꾸거나 Playground에서 파일을 업로드하세요. 같은 입력은 다시 실패합니다.
render_timeout	영상: 대기나 렌더링이 너무 오래 걸려 업스트림이 작업을 포기했습니다.	다시 제출하세요.
wait_timeout	영상: 120분 안에 결과가 나오지 않아 시간 초과로 처리하고 크레딧을 전액 환불했습니다. 이후 생성이 완료되면 영상은 무료로 제공합니다.	다시 제출하세요.
upstream_unstable	영상: 렌더링 중에 연결이 끊겼습니다.	다시 제출하세요.
result_fetch_failed	영상은 생성되었지만, 당사 측에서 영상을 내려받거나 저장하는 데 계속 실패했습니다.	다시 제출하세요.
upstream_error	그 밖의 실패: 자동 재시도 후에도 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 `message`에 있습니다.	다시 제출하면 대개 성공합니다.

message의 문구가 아니라 code로 판단하세요. 모르는 code가 오거나 code가 없으면 upstream_error로 처리하면 됩니다. 다시 제출하면 대개 성공합니다. 실패한 작업은 모두 전액 환불됩니다.

조회 대신 웹훅으로 받기

제출할 때 callback_url을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. 웹훅 문서 →

curl · callback_url

curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.0-fast", "prompt": "비 오는 밤 네온 불빛의 거리, 고인 빗물을 따라 떠내려가는 종이배, 낮은 앵글로 뒤따르는 카메라, 선명한 물보라와 물에 비친 반영", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'

Seedance 2.0 Fast · API

빠른 시작

인증

사양 한눈에 보기

요청 파라미터

가격

참조 소재

콘텐츠 요건

심사 시점

과금 없음

소리

자주 거절되는 내용

긴 스토리보드 대본

실존 인물

거절된 뒤

작업 상태와 응답 필드

생성 시간

오류와 환불

제출할 때 돌아오는 오류

작업 실패(status가 failed)

조회 대신 웹훅으로 받기

다시 오신 것을 환영합니다

계정 만들기

비밀번호 재설정

작업 실패(`status`가 `failed`)