NezhaGateNezhaGate
seedance-2.5-token

Seedance 2.5 · Token · API

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

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

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

완성 영상을 바로 생성하거나 초안을 확인한 뒤1080p로 렌더링하세요. 용도를 선택하면 해당 매개변수와 예제가 표시됩니다.

무엇을 하시겠어요?

완성 영상 바로 생성

현재 단계의 매개변수
파라미터타입설명
model필수string
prompt선택string텍스트 프롬프트입니다. prompt 또는 content 중 하나를 사용하세요. 초안 화질 향상 외에는 필수입니다.
content선택arraytext/image_url/video_url/audio_url 블록. HTTPS 참조 URL로 최대 이미지 30개, 동영상 10개, 오디오 10개를 지원합니다. 공급자 소재 ID는 허용하지 않습니다.
duration선택integer4~30초, 기본값 5초. 화질 향상 시 생략하세요.
resolution선택string
ratio선택stringadaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
output_format선택stringmp4 / mov. 일반 용도는 MP4. MOV는 다운로드 후 호환 플레이어가 필요할 수 있습니다.
고급: 표준 모델로 초안 생성

seedance-2.5-token에 draft: true와 resolution: 480p를 명시하세요. draft가 없는 일반480p는 업그레이드할 수 없습니다.

요청 예시

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

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

cURL · POST /v1/videos/generations

응답

202 · JSON
전체 호출 예제 · Python 3 · 480p → 1080p

초안 → 1080p

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

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

Python 3이며 추가 라이브러리는 필요 없습니다. NEZHAGATE_API_KEY를 설정하고 한 번 실행하면 초안 생성, 조회, 업그레이드를 수행합니다. 초안과 완성 영상은 별도 과금됩니다. 기존 작업 조회를 위해 전체 스크립트를 다시 실행하지 마세요.

Python 3 · 480p → 1080p
import json
import os
import time
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

BASE_URL = "https://nezhagate.com"
API_KEY = os.environ["NEZHAGATE_API_KEY"]


def request(path, payload=None):
    data = json.dumps(payload).encode() if payload is not None else None
    req = Request(BASE_URL + path, data=data, headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    })
    with urlopen(req, timeout=60) as response:
        return json.load(response)


def submit(payload):
    # Do not automatically retry a POST: its outcome may be unknown.
    job = request("/v1/videos/generations", payload)
    job_id = job["id"]
    print("Submitted:", job_id, flush=True)
    return job_id


def wait_for(job_id):
    deadline = time.monotonic() + 1800
    while time.monotonic() < deadline:
        try:
            job = request("/v1/videos/jobs/" + job_id)
        except HTTPError as exc:
            if exc.code != 429 and exc.code < 500:
                raise
            time.sleep(10)
            continue
        except (URLError, TimeoutError):
            time.sleep(10)
            continue
        progress = job.get("progress", {})
        print(job_id, job["status"], progress.get("phase", ""), flush=True)
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(json.dumps(job.get("error"), ensure_ascii=False))
        time.sleep(5)
    raise TimeoutError("Keep polling this job; do not resubmit: " + job_id)


if __name__ == "__main__":
    # Two separately billed tasks. Save the printed IDs to resume polling.
    draft_id = submit({
        "model": "seedance-2.5-token-draft",
        "prompt": "A sunrise over the sea",
        "duration": 5,
        "resolution": "480p",
    })
    draft = wait_for(draft_id)
    print("Draft video:", draft["data"][0]["url"])

    final_id = submit({
        "model": "seedance-2.5-token",
        "draft_task_id": draft_id,
        "resolution": "1080p",
    })
    final = wait_for(final_id)
    print("Final video:", final["data"][0]["url"])

인물 및 참조 소재

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

업로드한 파일은 선택하거나 삭제할 수 있습니다. Run 확인 및 잔액 예약 성공 후 소재 등록과 검토를 시작합니다.

단계설명
1. 파일 업로드인물 이미지를 공개 HTTPS 저장소에 업로드합니다. JSON은 로컬 경로나 바이너리를 받지 않습니다.
2. 참조 제출content에 image_url을 전달하고 프롬프트에서 @Image1로 인물을 참조합니다.
3. 가져오기 및 검토NezhaGate가 자동으로 가져오고 검토를 기다립니다. 소재 그룹 생성이나 asset:// ID 전달은 필요 없습니다.
4. 결과 확인같은 작업의 progress를 조회합니다. 소재 거절 시 failed와 error를 반환하고 영상 생성을 제출하지 않습니다.
  • 이미지 30개, 영상 10개, 오디오 10개, 총 50개까지. 참조 영상 합계 30초, 오디오 합계 30초. 웹 업로드: 이미지 <30MB, 영상 50MB, 오디오 15MB. API JSON은 HTTPS URL만 받으며 로컬 경로나 바이너리는 받지 않습니다. 원본 이미지 유지. 각 30MB 미만, 각 변 301–5999px, 비율 0.4–2.5. 인물 소재 준비 완료 후 사용. 일반 용도는 MP4. MOV는 다운로드 후 호환 플레이어가 필요할 수 있습니다.
  • data[0].source_url — 영상 서비스가 반환한 원본 링크는 만료될 수 있습니다. 즉시 저장하거나 당사에 보관된 원본 파일을 다운로드하세요.
cURL · 인물 및 참조 소재
curl https://nezhagate.com/v1/videos/generations \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "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 추가 필드이며 누락 필드와 향후 단계에 대응해야 합니다.

cURL · GET /v1/videos/jobs/{id}
curl https://nezhagate.com/v1/videos/jobs/img_example -H '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작업 실패
  • 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를 조회하세요. 중간 단계 웹훅은 추가하지 않습니다.
200 · 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"
  }
}

콘텐츠 요건

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

심사 시점

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

과금 없음

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

소리

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

자주 거절되는 내용

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

긴 스토리보드 대본

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

실존 인물

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

거절된 뒤

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

오류 코드: content_policy · status: failed

오류 코드

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

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

전체 오류 코드 목록 →