# Seedance 2.0 Fast — /videos/generations

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

**엔드포인트:** `POST https://kovapi.com/v1/videos/generations`

## 빠른 시작

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

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

```
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)

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

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

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

성공했을 때의 응답

```
{
  "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: 제출 → 대기 → 로컬에 저장)**

```
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로 이어서 조회하면 됩니다.

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 사양 한눈에 보기

| 길이 | 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 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}`는 아래 상태를 돌려줍니다. 각 필드의 설명은 [비동기 작업](https://docs.kovapi.com/ko/guide/async-jobs#fields)에 있습니다. 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로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 [오류 코드](https://docs.kovapi.com/ko/guide/errors)에 있습니다.

### 제출할 때 돌아오는 오류

| 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 레퍼런스](https://docs.kovapi.com/ko/api)에 있는 모델 ID를 쓰세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 [서비스 상태](https://kovapi.com/ko/status)에서 볼 수 있습니다. |
| 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로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. [웹훅 문서 →](https://docs.kovapi.com/ko/webhooks)

```
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"}'
```