Seedance 2.5

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

모델 ID

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

간단한 예제

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -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/contents/generations/tasks

요청 본문은 공식 ModelArk의 "동영상 생성 작업 만들기" 요청 그대로입니다. 이미 ModelArk를 호출하고 있다면 base URL을 https://api.seedrouter.ai/v1로 바꾸고 API 키만 교체하면 됩니다. 응답은 완성된 동영상이 아니라 {"id": "task_..."}입니다. API 키는 서버 측 코드에 보관하세요.

파라미터

content 항목

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

모드

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

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

참조 예제

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -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토큰입니다.

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

출력 스키마

제출하면 작업 ID가 반환됩니다:

{"id": "task_..."}

작업 조회

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

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

전체 폴링 예제

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

import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/contents/generations/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        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": "succeeded",
  "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,
  "created_at": 1790321515,
  "updated_at": 1790321652
}

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

작업 목록

curl "https://api.seedrouter.ai/v1/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded" \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

최근 7일간의 작업 객체를 최신순으로 담은 {"total": N, "items": [...]}를 반환합니다. page_num과 page_size는 1~500입니다(기본값은 각각 1과 20). 필터: filter.status, filter.model, filter.task_ids(반복 가능), filter.service_tier.

오류

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