Seedance 2.5 API: 호출 방법, 파라미터, 제한, 크레딧 비용

핵심 답변: 키 하나로 Yovid API를 통해 Seedance 2.5를 호출할 수 있습니다. "model": "seedance-2.5"와 프롬프트를 담아 POST https://yovid.ai/v1/videos/generations를 보낸 뒤, 상태가 completed가 될 때까지 GET /v1/tasks/{task_id}를 폴링하고 output.video_url을 읽으면 됩니다. 클립 길이는 4~30초이고, 요청 하나에 이미지 30개, 영상 10개, 오디오 파일 10개까지 참조로 담을 수 있습니다. 과금은 웹사이트와 같은 Yovid 크레딧으로 이뤄지며, 크레딧은 작업이 성공했을 때만 차감됩니다.

목차

1. Seedance 2.5 API 제공 경로
2. 4단계 빠른 시작
3. 요청 파라미터
4. API가 생성 모드를 고르는 방식
5. 참조와 미디어 제한
6. 요청 하나에 드는 비용
7. 오류, 재시도, 속도 제한
8. 전체 Python 예제
9. 자주 묻는 질문

Seedance 2.5 API 제공 경로

Seedance 2.5는 ByteDance Seed의 모델입니다. ByteDance가 직접 제공하는 개발자 경로는 자사 클라우드 플랫폼을 거칩니다. 2026년 7월 31일 출시 글에서는 BytePlus ModelArk를 통한 API 접근을 곧 제공한다고 밝혔고, 언론 보도에 따르면 Volcano Engine은 8월 7일 중국에서 API 접근을 열었으며, ByteDance의 Seedance 2.5 페이지는 BytePlus 플레이그라운드로 연결됩니다.

Yovid는 ByteDance와 제휴 관계가 없는 독립 플랫폼이며, 자체 API로 Seedance 2.5를 제공합니다.

• 키 하나, 청구서 하나. 같은 키와 같은 크레딧으로 Seedance 2.5, 2.0, 2.0 Fast, 2.0 Mini, 1.5 Pro, 1.0 Pro Fast를 모두 쓸 수 있습니다.
• 안정적인 공개 ID. seedance-2.5만 보내면 됩니다. Yovid는 공급사 모델명을 내부에서만 관리하므로, 공급사 쪽 이름이 바뀌어도 코드가 깨지지 않습니다.
• 웹사이트와 같은 계정. API로 생성하는 클립에도 이미 가진 플랜과 크레딧이 그대로 적용됩니다.

전체 레퍼런스는 Yovid API 문서에 있습니다. 이 가이드는 Seedance 2.5에만 해당하는 내용을 다룹니다.

4단계 빠른 시작

1. API 키 만들기

설정 → API 키를 열고 키 이름을 정한 다음 만드세요. 전체 시크릿은 한 번만 표시되니 시크릿 매니저에 저장하고, 서버에서 YOVID_API_KEY로 불러오세요. 브라우저나 모바일 앱 코드에는 절대 넣지 마세요.

2. 작업 만들기

curl https://yovid.ai/v1/videos/generations \
  -H "Authorization: Bearer $YOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse keeper climbs a spiral staircase with a lantern, reaches the lamp room as a storm rolls in, and lights the great lamp. Wind howling, boots on iron steps.",
    "duration": 10,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

{
  "task_id": "vid_01JZK7R7KCYQ3T9F33A7K0J6XB",
  "status": "pending",
  "created_at": "2026-10-22T08:30:00.000Z"
}

3. 작업 폴링하기

curl https://yovid.ai/v1/tasks/vid_01JZK7R7KCYQ3T9F33A7K0J6XB \
  -H "Authorization: Bearer $YOVID_API_KEY"

상태가 pending이나 processing인 동안 5~10초마다 폴링하되, 갈수록 간격을 늘리세요. completed로 바뀌면 영상 URL이 output.video_url에 들어 있고, failed로 바뀌면 폴링을 멈추고 error를 확인하세요.

4. 크레딧 확인하기

curl https://yovid.ai/v1/credits \
  -H "Authorization: Bearer $YOVID_API_KEY"

available은 새 작업에 쓸 수 있는 크레딧이고, reserved는 아직 실행 중인 작업을 위해 묶여 있는 크레딧입니다.

요청 파라미터

API는 작업을 만들기 전에 모든 값을 모델과 플랜 기준으로 검사하고, 허용되지 않는 값이 있으면 문제가 된 필드를 param에 담아 403이나 422를 반환합니다. 프레임으로 시작하면 출력 영상은 그 이미지의 비율을 따릅니다.

API가 생성 모드를 고르는 방식

공급사 모드를 직접 보낼 필요는 없습니다. Yovid가 첨부한 미디어를 보고 모드를 고릅니다.

참조 모드에서는 각 배열 안의 순서대로 프롬프트에서 파일을 부르세요: @image1, @image2, @video1, @audio1. 참조 요청은 다음과 같습니다.

{
  "model": "seedance-2.5",
  "prompt": "@image1 is the main character. @image2 is the ceramic mug she holds; keep its shape and logo. @image3 is the kitchen. She walks into the kitchen, pours coffee into the mug and turns to the window. Use @audio1 as her voice: she says, \"Finally, Saturday.\"",
  "image_urls": [
    "https://example.com/character.jpg",
    "https://example.com/mug.jpg",
    "https://example.com/kitchen.jpg"
  ],
  "audio_urls": ["https://example.com/voice-sample.mp3"],
  "duration": 12,
  "quality": "720p"
}

오디오 참조는 API 전용 기능입니다. 웹사이트 입력창은 이미지와 영상을 받고, API는 여기에 목소리, 음악, 리듬을 위한 오디오 파일을 최대 10개까지 더합니다.

참조와 미디어 제한

API 문서의 모델과 입력 페이지에서 가져온 내용입니다.

모든 미디어는 공개 HTTPS URL이어야 합니다. Yovid는 localhost, 사설 네트워크 주소, 인증 정보가 포함된 URL, 확인할 수 없는 호스트명을 거부합니다. Base64 대신 URL을 쓰세요. 공급사가 요청 본문을 요청당 64MB로 제한합니다.

요청 하나에 드는 비용

API는 웹사이트와 같은 요금표로 같은 크레딧을 청구합니다. 크레딧 팩 기본 요금으로 Seedance 2.5는 480p에서 초당 약 3크레딧, 720p에서 약 6.1크레딧이므로, 720p 10초 클립은 약 61크레딧, 30초 클립은 약 183크레딧입니다. 구독자는 초당 비용이 더 낮습니다.

• 참조 영상은 참조 클립 길이와 출력 길이를 합산해 더 낮은 요금으로 청구됩니다. 480p는 초당 약 2.1크레딧, 720p는 4.6크레딧입니다.
• content_filter를 끄면 비용이 1.1배가 됩니다.
• 예약 후 차감. 크레딧은 작업을 만들 때 예약되고, 작업이 완료됐을 때만 차감됩니다. 실패한 작업은 크레딧을 돌려줍니다.
• 플랜 조건. Seedance 2.5에는 유료 플랜이나 일회성 크레딧 팩이 필요합니다. 무료 계정은 403 plan_upgrade_required를 받습니다.

완료된 작업은 사용한 크레딧을 credits_used에 담아 알려 줍니다. 플랜과 크레딧 팩은 요금제 페이지에서, 가장 저렴하게 시작하는 방법은 Seedance 2.5는 무료일까에서 확인하세요.

오류, 재시도, 속도 제한

키 하나당 분당 최대 120회까지 요청할 수 있고, 폴링도 여기에 포함됩니다. 생성 엔드포인트는 아직 멱등성 키를 지원하지 않으므로, 첫 요청이 성공했는지 모르는 상태에서 POST를 자동으로 재시도하지 마세요. 작업이 두 개 생기고 크레딧이 두 번 예약될 수 있습니다. 받은 task_id는 모두 기록해 두세요.

전체 Python 예제

import os
import time

import requests

API = "https://yovid.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['YOVID_API_KEY']}"}

create = requests.post(
    f"{API}/v1/videos/generations",
    headers=HEADERS,
    json={
        "model": "seedance-2.5",
        "prompt": (
            "0-10s: a courier in a yellow rain jacket runs out of a subway exit into a night street. "
            "10-20s: she weaves between umbrellas as a taxi brakes. "
            "20-30s: she stops at a door and knocks twice. Rain and traffic, no music."
        ),
        "duration": 30,
        "quality": "720p",
        "aspect_ratio": "16:9",
    },
    timeout=30,
)
create.raise_for_status()
task_id = create.json()["task_id"]

delay = 5
while True:
    task = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
    task.raise_for_status()
    data = task.json()
    if data["status"] == "completed":
        print(data["output"]["video_url"], data["credits_used"])
        break
    if data["status"] == "failed":
        raise RuntimeError(data["error"])
    time.sleep(delay)
    delay = min(delay * 1.5, 30)

이 프롬프트는 30초 클립을 채우는 가장 확실한 방법인 시간대별 비트를 씁니다. Seedance 2.5 프롬프트 가이드에는 그대로 보낼 수 있는 프롬프트 13개가 있고, Kling 3.0, Veo 3.1, Seedance 2.0과의 비교 글은 어떤 모델 ID를 호출할지 고르는 데 도움이 됩니다.

자주 묻는 질문

Seedance 2.5 공식 API가 있나요?

ByteDance는 자사 클라우드 플랫폼인 Volcano Engine과 BytePlus를 통해 개발자에게 Seedance 2.5를 제공합니다. Yovid API는 독립적인 대안으로, 키 하나와 크레딧 잔액 하나로 Seedance 2.5와 다른 Seedance 모델을 모두 쓸 수 있습니다.

Yovid에서 Seedance 2.5의 모델 ID는 무엇인가요?

seedance-2.5입니다. 다른 공개 ID로는 seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-1.5-pro, seedance-1.0-pro-fast가 있습니다.

Seedance 2.5 API 영상은 최대 몇 초까지 만들 수 있나요?

작업당 4~30초이며, duration으로 설정합니다.

Seedance 2.5 API는 어떤 해상도를 지원하나요?

API 문서에는 seedance-2.5용으로 480p와 720p가 나와 있습니다. 플랜에 따라서도 상한이 정해지며, 화질이 상한을 넘으면 API가 작업을 만들기 전에 403을 반환합니다.

오디오를 참조로 보낼 수 있나요?

네. audio_urls에 MP3 또는 WAV 파일을 최대 10개까지 넣고, 프롬프트에서는 @audio1, @audio2처럼 순서대로 부르면 됩니다. 오디오 참조는 API에서만 쓸 수 있습니다.

실패한 작업에도 크레딧이 드나요?

아니요. 크레딧은 작업을 만들 때 예약되고, 작업이 성공적으로 완료됐을 때만 차감됩니다.

요청은 얼마나 보낼 수 있나요?

키당 분당 최대 120회(폴링 포함)이며, 여기에 플랜에 따라 달라지는 동시 작업 한도가 더해집니다. 429 응답을 받으면 잠시 기다렸다가 백오프를 적용해 재시도하세요.

개발을 시작할 준비가 되었다면 설정 → API 키에서 키를 만들고 API 빠른 시작을 따라 해 보세요.