Seedance 2.5

Seedance 2.5는 ByteDance의 최신 동영상 생성 모델(Dreamina Seedance 2.5)입니다. 공식 ModelArk 작업 요청 본문을 POST /v1/videos/generations으로 보내고, 반환된 작업 ID를 보관한 뒤 GET /v1/tasks/{id}에서 완성된 동영상을 받아오세요. 이미지, 동영상, 오디오는 content에 URL로 넣습니다.

모델 ID

현재 가격은 모델 페이지에서 확인하세요.

간단한 예제

curl https://api.seedrouter.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

엔드포인트

POST https://api.seedrouter.ai/v1/videos/generations

요청 본문은 공식 ModelArk의 "동영상 생성 작업 만들기" 요청 본문입니다. 이는 모든 SeedRouter 동영상 모델이 사용하는 동일한 엔드포인트입니다. 응답은 완성된 동영상이 아니라 새 작업(id, status: "processing")입니다. API 키는 서버 측 코드에 보관하세요.

파라미터

content 항목

알 수 없는 필드는 거부됩니다. 지원하지 않는 항목: seed, callback_url(대신 작업을 폴링하세요), tools, 그리고 1.x 전용인 frames와 camera_fixed. 작업은 취소하거나 삭제할 수 없습니다.

모드

모드는 content 항목에 따라 정해지며, 모드 파라미터는 없습니다.

첫 프레임 계열 모드는 참조 항목과 함께 쓸 수 없습니다. 이미지가 여러 장이거나 다른 미디어가 함께 있으면 모든 이미지에 role이 필요합니다.

참조 예제

curl https://api.seedrouter.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

예제의 URL은 접근 가능한 본인의 파일로 바꾸세요.

미디어 입력

이 API는 URL 참조만 받습니다. Base64, data: URL, asset:// ID, multipart 업로드는 받지 않습니다. Playground는 선택한 파일을 스토리지에 업로드한 뒤 그 URL을 전송합니다.

미디어는 공개 HTTP(S) URL이어야 하며 모델의 공식 제한을 충족해야 합니다:

실제 사람의 얼굴이 담긴 참조 이미지와 참조 동영상은 모델에서 지원하지 않습니다.

미디어는 작업이 시작될 때, 생성에 앞서 검사됩니다. 미디어가 이 제한 중 하나라도 어기면 작업은 invalid_request_error와 위반한 규칙을 알려 주는 메시지(예: The request was rejected: content reference videos must total at most 15 seconds.)와 함께 failed로 끝나며 과금되지 않습니다. 그 시점에 읽을 수 없는 파일은 모델에 그대로 전달되고, 모델이 받아들이거나 거부합니다. 어느 쪽이든 실패한 작업은 과금되지 않습니다.

과금에 영향을 주는 요소

현재 요금은 모델 가격 섹션에서 확인하세요. Seedance 2.5는 공식 단위인 동영상 토큰으로 과금합니다:

video tokens = (output seconds + reference video seconds) × width × height × 24 / 1024

100만 토큰당 요율은 출력 해상도와 요청에 참조 동영상이 포함되는지 여부에 따라 달라집니다. 참조 동영상이 포함된 요청은 모든 토큰에 더 낮은 요율이 적용됩니다. 텍스트, 이미지, 오디오 입력은 과금되지 않습니다. 16:9 기준으로 1초는 480p(854×480)에서 9,607.5토큰, 720p에서 21,600토큰, 1080p에서 48,600토큰입니다.

참조 영상이 포함된 요청에는 최소 토큰 기준도 적용됩니다. 예상 비용을 계산할 때는 원본 참조 영상이 더 짧더라도 공식의 참조 영상 길이를 최소 ceil(output seconds × 2 / 3)초로 계산하세요. 이 규칙은 초안과 최종 영상 작업 모두에 적용되며, 초안 영상 자체가 참조 영상이 되는 것은 아닙니다. 실제 요금은 완료된 작업이 반환하는 사용량을 기준으로 합니다.

과금은 완성된 동영상이 보고하는 토큰(output.usage.completion_tokens)을 따르므로, duration: -1은 실제로 생성된 길이를 기준으로 과금됩니다. 렌더링된 클립은 요청한 길이보다 약간 길게 나옵니다. 5초 720p 16:9 요청은 121프레임으로 렌더링되며 108,000토큰이 아니라 108,900토큰이 보고됩니다. 최종 과금액은 계정의 사용 내역에서 확인하세요. 실패한 작업은 과금되지 않습니다.

출력 스키마

제출하면 새 작업이 반환됩니다:

{"id": "task_...", "model": "dreamina-seedance-2-5", "status": "processing", "created_at": 1790321515}

작업 조회

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

status가 completed 또는 failed가 될 때까지 10~20초마다 폴링하세요. 폴링 중 네트워크 타임아웃이 발생해도 생성이 실패한 것은 아닙니다. 작업 ID를 유지한 채 조회를 이어가세요. 진행 상황 확인을 위해 다른 작업을 만들지 마세요.

전체 폴링 예제

위의 Python 제출 예제 다음에 실행하세요.

import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        print(task["output"]["video_url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

완료된 작업

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "completed",
  "created_at": 1790321515,
  "finished_at": 1790321652,
  "output": {
    "video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4",
    "last_frame_url": "https://static.seedrouter.ai/media/tasks/task_example/last_frame/0.jpg",
    "content": {
      "video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4",
      "last_frame_url": "https://static.seedrouter.ai/media/tasks/task_example/last_frame/0.jpg"
    },
    "usage": {"completion_tokens": 108900, "total_tokens": 108900},
    "seed": 42,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "framespersecond": 24,
    "generate_audio": true,
    "draft": false,
    "output_format": "mp4",
    "service_tier": "default",
    "execution_expires_after": 172800,
    "priority": 0
  }
}

동영상 URL은 저희 스토리지에 호스팅됩니다. 오래 보관해야 한다면 파일을 직접 스토리지에 저장하세요.

오류

작업이 생성되기 전에 거부된 요청은 HTTP 오류와 error 객체를 반환하며 과금되지 않습니다. 접수된 뒤 실패한 작업은 조회 시 HTTP 200과 함께 status: "failed" 및 error 객체를 반환합니다. 콘텐츠 필터링으로 출력이 보류되면 content_policy_violation으로 실패하고, execution_expires_after를 넘겨 실행된 작업은 task_expired로 실패합니다.

코드, HTTP 상태, 재시도 지침은 공통 오류 카탈로그를 참고하세요.

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

제출 자체가 타임아웃된 경우에는 다시 보내기 전에 작업 내역을 확인하세요. 첫 번째 요청이 이미 접수되었을 수 있습니다.

팁

• 피사체, 동작, 카메라 움직임, 조명을 완전한 문장으로 설명하세요.
• 480p와 짧은 duration으로 초안을 만든 뒤, 마음에 드는 결과를 더 높은 해상도로 렌더링하세요.
• return_last_frame으로 샷을 이어 붙이세요. 반환된 프레임을 다음 작업의 first_frame으로 사용하면 됩니다.
• 영상을 편집하려면 omni_reference_task_type을 edit로 설정하고, 바뀌어야 할 부분만 설명하세요.

관련 자료

• Seedance 2.5 Playground와 가격
• OpenAPI 다운로드
• 복사 가능한 Markdown

초안 미리보기와 최종 영상

draft: true로 설정하면 480p 미리보기를 생성합니다. 초안 모드에서는 다른 해상도를 사용할 수 없습니다. 미리보기 생성의 토큰 사용량 계산 방식과 단가는 표준 480p 생성과 같습니다.

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "text", "text": "A fox walks through a sunny garden." }],
  "draft": true,
  "resolution": "480p",
  "duration": 4,
  "ratio": "16:9"
}

반환된 SeedRouter 작업 ID를 폴링하여 status가 completed이고 output.draft가 true인지 확인하세요. 초안 작업 생성 후 7일 이내에 해당 ID로 별도의 요청을 제출하세요.

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "draft_task", "draft_task": { "id": "task_YOUR_DRAFT_ID" } }],
  "resolution": "1080p"
}

초안은 본인 계정 소유이며 생성에 완료된 상태여야 하고, 동일한 모델을 사용해야 합니다. content에는 draft_task 항목 하나만 포함할 수 있습니다. resolution을 1080p로 명시하고, draft는 생략하거나 false로 설정하세요. duration, ratio, seed, generate_audio, omni_reference_task_type, 텍스트 또는 미디어는 값이 같더라도 다시 보내면 안 됩니다. 이 설정들은 초안에서 상속됩니다.

새 작업에는 watermark, return_last_frame, output_format, execution_expires_after, priority, safety_identifier, service_tier: "default"를 설정할 수 있습니다. 생략한 출력 옵션에는 각 기본값이 적용됩니다. content_filter는 초안에서 상속되며 변경할 수 없습니다. 최종 영상 생성에 성공하면 새 작업 ID, output.draft: false, 원래 SeedRouter 초안 ID가 담긴 output.draft_task_id가 반환됩니다. 만료 전까지 하나의 초안으로 최종 영상을 여러 번 별도로 생성할 수 있습니다.

초안과 최종 영상은 각각 별도로 과금됩니다. 최종 영상에는 원래 초안의 입력 유형에 해당하는 1080p 요율이 적용됩니다. 초안에 참조 영상을 사용했다면 최종 영상에도 참조 영상 요율이 적용되며, 원본 참조 영상의 길이가 토큰 사용량에 포함됩니다. 초안 영상 자체는 추가 입력 영상으로 계산되지 않습니다. 각 작업에는 제출 시점에 유효한 가격이 적용됩니다. 실패한 요청에는 요금이 부과되지 않습니다.