# Seedance 2.0 Mini — /videos/generations

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

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

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

## 요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `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일간 보관됩니다. |

## 요청 예시
```bash
# 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'
```

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

## 콘텐츠 요건

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`