Seedance 2.0 Mini

텍스트, 첫 프레임과 마지막 프레임, 또는 참조로 쓰는 최대 9장의 이미지·3개의 영상·3개의 오디오 클립으로 Seedance 제품군에서 가장 낮은 정가로 480p 또는 720p의 4–15초 영상을 생성합니다(과금 참고).

• 비동기 방식: 생성 호출은 작업 ID를 반환하고, 작업이 성공하면 영상이 제공됩니다(보통 몇 분).
• 네 가지 입력 방식: 텍스트만, 첫 프레임, 첫 프레임과 마지막 프레임, 또는 참조 이미지·영상·오디오의 자유로운 조합(오디오에는 이미지나 영상이 하나 이상 함께 필요).
• 480p와 720p만 제공하며, Seedance 제품군에서 정가가 가장 낮습니다(과금 참고).
• 이 모델에는 generate_audio 필드가 없으며, 보내면 거부됩니다. 소리를 제어하려면 Seedance 2.0 또는 2.0 Fast를 사용하세요.
• 영상의 크기와 길이, 그리고 참조 영상의 길이에 따라 과금됩니다. 실패한 작업은 비용이 들지 않습니다.

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델 ID

Seedance 모델 네 개가 이 엔드포인트를 함께 씁니다. 아래 값은 게이트웨이 계약에서 그대로 가져왔으며, task_type, output_format, seed는 Seedance 2.5만 받습니다.

엔드포인트와 인증

POST https://api.beatapi.io/v1/videos/tasks

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

입력 모드

요청 파라미터

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

• images는 참조 입력과 함께 쓸 수 없습니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

• 참조 영상은 바이트 범위 요청에 응답하는 호스트의 공개 HTTPS 링크에 있는 MP4 또는 MOV여야 합니다. 초 수가 과금되므로 길이를 읽을 수 없는 클립은 항상 거부됩니다.
• 이미지 크기는 호스트가 알려 줄 때 검사합니다. JPEG, PNG 또는 WebP를 사용하세요. 모델이 쓸 수 없는 파일은 제출 후 bad_request로 작업이 실패하며 환불됩니다.
• 제한은 길이, 변 길이, 화면비, 픽셀 수, 프레임 속도, 크기 순으로 보고됩니다. 메시지는 필드 오류와 마찬가지로 0부터 세어 목록과 위치로 입력을 명시합니다: reference_videos[0] is 1.5 seconds long; this model takes reference video of 1.8 to 15 seconds.
• 길이는 0.1초의 허용 오차로 측정합니다. 크기는 호스트가 알려 줄 때만 검사합니다.
• 이미지와 오디오 링크는 호스트가 4xx 오류로 응답하거나 빈 파일을 반환할 때만 작업 생성 시 거부됩니다(예: images[1] could not be downloaded: the URL returned HTTP 404.). 다른 문제는 제출 후에 드러납니다.
• 23.976 FPS 클립은 24 미만으로 간주되어 거부됩니다. 24 FPS 이상으로 다시 내보내세요.
• 로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

조합 규칙

다음은 작업 생성 시 이 순서로 검사합니다. 하나라도 어긴 요청은 400 bad_request로 거부되며 비용이 들지 않습니다.

이 모델이 받지 않는 필드

다음 필드를 보내면 무시되지 않고 과금 전에 거부됩니다.

• generate_audio(Mini에서는 제공 안 함), seed, task_type, output_format(Seedance 2.5 전용), watermark, quality, sound, multi_shots, character_orientation 같은 다른 영상 모델의 필드 → field "generate_audio" is not supported by model seedance-2-mini(보낸 필드 명시).
• BeatAPI 영상 모델에 없는 이름 → unknown field: <name>.

가격 추정

작업의 영상 토큰은 N = W × H × (24 × D + 1 + 24 × R) / 1024입니다. W × H는 선택한 해상도와 화면비의 프레임 크기(픽셀)로 720p 16:9는 1280 × 720, 480p 16:9는 864 × 496이며, D는 출력 길이(초), R은 참조 영상의 총 길이(초, 없으면 0)입니다. 가격은 N에 영상 토큰 100만 개당 요금을 곱한 값으로, 480p와 720p 모두 참조 영상이 없으면 약 $3.466, 있으면 약$2.110입니다.

예를 들어 참조 영상 없이 720p 16:9로 5초이면 1280 × 720 × 121 / 1024 = 108,900 토큰, 약 $0.377입니다. 참조 클립의 길이는 게이트웨이가 직접 측정하므로 보낼 필요가 없습니다. 이는 추정치이며, 작업의 usage에 보류·청구 금액이 표시됩니다.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "A handheld tracking shot through a rain-lit night market, neon reflections on wet stone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

텍스트로 영상 생성

720p 가로 5초 클립입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "A handheld tracking shot through a rain-lit night market, neon reflections on wet stone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

첫 프레임

이미지에서 영상이 시작됩니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "Animate the singer with a quick natural camera push-in",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "720p"
}'

첫 프레임과 마지막 프레임

첫 번째 이미지에서 두 번째 이미지로 이어지는 영상입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 6,
  "resolution": "720p"
}'

이미지와 오디오 참조

인물 이미지와 음악 클립을 따르는 퍼포먼스입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p"
}'

이미지, 영상, 오디오 참조

영상 링크를 직접 준비한 15초 이하의 MP4 또는 MOV로 바꾸세요. 참조 영상은 모든 초가 과금됩니다(과금 참고).

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2-mini",
  "prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video, cut to the beat of the reference music",
  "reference_images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p"
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2-mini",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2-mini",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.291643,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.291643,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2-mini",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2-mini",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.291643,
      "credits_settled": 0.291643,
      "credits_refunded": 0,
      "credits_charged": 0.291643,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2-mini",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2-mini",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.291643,
      "credits_settled": 0,
      "credits_refunded": 0.291643,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "seedance-2-mini",
  "prompt": "A handheld tracking shot through a rain-lit night market, neon reflections on wet stone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

• 가격은 영상의 크기와 길이에 따라 정해집니다. 초 수가 많을수록, 해상도가 높을수록, 프레임이 클수록 비쌉니다. 참조 이미지와 오디오는 추가 비용이 없습니다.
• 참조 영상 없이 16:9 클립은 초당 약 $0.027(480p) 또는$0.058(720p)입니다. 다른 화면비는 몇 퍼센트 차이가 납니다.
• reference_videos를 쓰면 요청 전체가 더 낮은 “영상 입력 포함” 요금으로 바뀌며, 참조 영상의 모든 초가 출력 초처럼 계산됩니다. 16:9 기준 출력과 참조 합계 초당 약 $0.016(480p) 또는$0.035(720p)입니다.
• 아래 표는 8초 클립 기준이며, “영상 입력 포함” 행에는 8초 참조 영상이 포함됩니다.
• 가격은 작업 생성 시 보류됩니다. adaptive를 쓰면 보류 금액은 해당 해상도의 가장 큰 프레임을 기준으로 합니다. 보류 금액을 지불하며, 제공된 영상의 실제 금액이 더 크면 실제 금액을 지불합니다.
• 실패한 작업은 제출 후 콘텐츠 검수에서 거부된 경우를 포함해 전액 환불됩니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

자주 발생하는 오류

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}