# Seedance 2.5 · Token — /videos/generations

실제 동영상 토큰으로 과금하는 비동기 영상 생성입니다. 초안과 화질 향상은 별도 유료 작업이며 참조 동영상의 토큰도 포함됩니다. 반환된 게이트웨이 작업 ID로 조회하세요. 클라이언트 시간 초과 후 다시 제출하지 마세요. 콘텐츠 검토가 적용됩니다. 검토 없는 모드는 제공하지 않습니다. BytePlus 공개 해외 USD 정가의 약 95%를 소수점 한 자리로 반올림한 요금입니다. 일반 용도는 MP4. MOV는 다운로드 후 호환 플레이어가 필요할 수 있습니다.

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

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

## 요청 본문
| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `model` | string | 예 | seedance-2.5-token |
| `prompt` | string | 아니오 | 텍스트 프롬프트입니다. prompt 또는 content 중 하나를 사용하세요. 초안 화질 향상 외에는 필수입니다. |
| `content` | array | 아니오 | text/image_url/video_url/audio_url 블록. HTTPS 참조 URL로 최대 이미지 30개, 동영상 10개, 오디오 10개를 지원합니다. 공급자 소재 ID는 허용하지 않습니다. |
| `duration` | integer | 아니오 | 4~30초, 기본값 5초. 화질 향상 시 생략하세요. |
| `resolution` | string | 아니오 | 480p / 720p(기본값) / 1080p. 초안은 480p가 필요합니다. 초안 화질 향상은 1080p만 지원합니다(기본값). |
| `ratio` | string | 아니오 | adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 |
| `draft` | boolean | 아니오 | true는 별도로 과금되는 480p 초안을 만듭니다. |
| `draft_task_id` | string | 아니오 | 현재 계정의 완료된 Token 초안 게이트웨이 작업 ID입니다. 화질 향상 시 model, draft_task_id, resolution과 선택적으로 watermark/callback_url만 보내세요. 초안 화질 향상은 1080p만 지원합니다(기본값). 본인 계정에서 완료된 Token 초안만 업그레이드할 수 있습니다. 초 단위 상품, 일반 480p 영상, 외부 작업 ID는 지원하지 않습니다. |
| `output_format` | string | 아니오 | mp4 / mov. 일반 용도는 MP4. MOV는 다운로드 후 호환 플레이어가 필요할 수 있습니다. |

## 요청 예시
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"seedance-2.5-token","prompt":"A sunrise over the sea","duration":5,"resolution":"720p"}'
# 2) poll every ~5s until status=succeeded, then read data[0].url
curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## 응답
```json
{"id":"img_example","object":"video.generation.job","status":"queued","model":"seedance-2.5-token"}
```

## 콘텐츠 요건

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

### 심사 시점

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

### 과금 없음

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

### 소리

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

### 자주 거절되는 내용

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

### 긴 스토리보드 대본

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

### 실존 인물

실존 인물의 사진을 참조로 쓰려면 그 사람의 초상을 사용할 권리가 있어야 합니다.

### 거절된 뒤

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

오류 코드: `content_policy` · `status: failed`

## 초안 → 1080p

본인 계정에서 완료된 Token 초안만 업그레이드할 수 있습니다. 초 단위 상품, 일반 480p 영상, 외부 작업 ID는 지원하지 않습니다.

480p 초안을 만들고 succeeded까지 조회합니다. NezhaGate 작업 ID를 draft_task_id로 일반 Token 모델에 보내면 원래 작업을 바탕으로 1080p 완성 영상을 생성합니다. 임의 MP4 확대 기능이 아닙니다. prompt, content, duration, ratio, seed, generate_audio를 다시 보내지 마세요. 초안과 완성 영상은 별도 과금됩니다.

`POST /v1/videos/generations`

```json

{
  "model": "seedance-2.5-token-draft",
  "prompt": "A sunrise over the sea",
  "duration": 5,
  "resolution": "480p"
}

```

`GET /v1/videos/jobs/{draft_job_id}`

`POST /v1/videos/generations`

```json

{
  "model": "seedance-2.5-token",
  "draft_task_id": "<completed NezhaGate draft job ID>",
  "resolution": "1080p"
}

```

`GET /v1/videos/jobs/{new_job_id}`

`data[0].source_url` — 영상 서비스가 반환한 원본 링크는 만료될 수 있습니다. 즉시 저장하거나 당사에 보관된 원본 파일을 다운로드하세요.

## 참조 소재 준비

API: 파일을 공개 HTTPS 저장소에 올린 뒤 content에 image_url, video_url, audio_url을 보냅니다. 작업 중 링크 접근을 유지하세요. NezhaGate가 소재 라이브러리로 가져오고 모두 Active가 된 후 생성합니다. 실존 인물 참조도 동일합니다. 업로드 완료가 준비 완료는 아닙니다. 별도 소재 API 호출은 필요 없습니다.

Playground: 파일 선택 → 업로드 진행 → 소재 준비 → 사용 가능 → 예약 금액 확인 및 생성. API는 두 단계 모두 GET /v1/videos/jobs/{id}로 같은 작업을 조회합니다. 타임아웃이 곧 실패는 아닙니다. 재제출 전 상태를 확인하고 실패한 링크를 수정하세요.

이미지 30개, 영상 10개, 오디오 10개, 총 50개까지. 참조 영상 합계 30초, 오디오 합계 30초. 웹 업로드: 이미지 <30MB, 영상 50MB, 오디오 15MB. API JSON은 HTTPS URL만 받으며 로컬 경로나 바이너리는 받지 않습니다. 원본 이미지 유지. 각 30MB 미만, 각 변 301–5999px, 비율 0.4–2.5. 인물 소재 준비 완료 후 사용. 일반 용도는 MP4. MOV는 다운로드 후 호환 플레이어가 필요할 수 있습니다.

```json

{
  "model": "seedance-2.5-token",
  "content": [
    {
      "type": "text",
      "text": "The character from @Image1 walks by the sea."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      }
    }
  ],
  "duration": 5,
  "resolution": "720p"
}

```

## 작업 상태 폴링

동일한 Bearer API 키로 GET /v1/videos/jobs/{id}를 3–5초마다 조회하세요. 소유 계정만 조회할 수 있습니다. 기존 status 유지: queued / processing은 계속 조회, succeeded는 data[0].url, failed는 error 확인. progress는 Token 추가 필드이며 누락 필드와 향후 단계에 대응해야 합니다.

phase는 처리 단계이며 백분율이나 예상 시간이 아닙니다. ready / total은 중복 제거된 준비 완료 / 필요 참조 수이며 텍스트 전용이나 업그레이드에서는 0일 수 있습니다. label과 detail은 영어 표시 문구로 분기 조건이 아닙니다. terminal은 최종 상태, failed_stage는 실패 외에는 null입니다. 복구 중 단계가 생략되거나 반복될 수 있습니다.

submitted=true는 생성 ID 확인, false는 전송 시작 전, null은 전송 시작 후 결과 미확정입니다. null이나 타임아웃으로 자동 재제출하지 마세요. reservation_released=true는 비용 0으로 해제 기록이 확인된 경우이며 false가 과금을 뜻하지 않습니다. updated_at은 작업 기록 갱신 시각, job_id는 NezhaGate 작업 ID입니다.

매개변수, 잔액, 프롬프트 사전 거절은 작업 생성 전 HTTP 오류이며 조회할 ID가 없습니다. 사전 검토 통과가 최종 승인을 보장하지 않습니다. 소재 가져오기/검토 실패는 생성을 중단하고 failed와 error를 반환합니다. 일시적 통신 오류에는 대기 시간을 늘려 동일 ID를 조회하세요. 중간 단계 웹훅은 추가하지 않습니다.

```http
GET /v1/videos/jobs/img_example
Authorization: Bearer YOUR_API_KEY
```

| progress.phase | |
| --- | --- |
| queued | 처리 대기 |
| preparing | 참조 소재 준비 중 |
| reviewing | 참조 소재 검토 중 |
| submitting | 생성 요청 전송 중 |
| provider_queued | 생성 대기 |
| generating | 영상 생성 중 |
| delivering | 영상 저장 중 |
| succeeded | 완료 |
| material_failed | 소재 거절 또는 가져오기 실패 |
| submission_failed | 생성 요청 전송 실패 또는 미확정 |
| generation_failed | 영상 생성 실패 |
| delivery_failed | 결과 저장 실패 |
| failed | 작업 실패 |

```json
{
  "id": "img_example",
  "object": "video.generation.job",
  "status": "processing",
  "created": 1792800000,
  "model": "seedance-2.5-token",
  "progress": {
    "phase": "reviewing",
    "label": "Reviewing references",
    "detail": "References ready: 3 / 5",
    "ready": 3,
    "total": 5,
    "terminal": false,
    "failed_stage": null,
    "submitted": false,
    "reservation_released": false,
    "updated_at": "2026-10-24T05:00:00+00:00",
    "job_id": "img_example"
  }
}
```