S
Seedance 2.0 API 가이드

Seedance 2.0 비디오 생성 API

TokenHub 통합 API를 통해 ByteDance Seedance 2.0 비디오 생성 model에 접근할 수 있습니다. 텍스트-비디오, 이미지-비디오, 비디오 편집, 오디오 기반 생성 등을 지원합니다. 이 가이드는 전체 통합 과정을 안내합니다.

Text → VideoImage → VideoVideo → VideoAudio Reference480p / 720p / 1080p4–15초

1API Key 받기

  1. 방문 tokenhub.store 계정 생성용 (GitHub / Google 로그인 지원)
  2. Dashboard → API Keys로 이동한 뒤 "Create New Key"를 클릭하세요
  3. Dashboard → Billing으로 이동해 Credits를 충전하세요 (1 Credit = $1 USD)
  4. API Key를 복사하세요 (형식: th-xxxxxxxxxxxx...
⚠️ API Key는 생성 시 한 번만 표시됩니다. 안전하게 보관하세요. 분실한 경우 새로 생성해야 합니다.

2API 개요

Base URL

https://tokenhub.store/api/v1

인증

모든 요청은 헤더에 API Key가 필요합니다:

Header
Authorization: Bearer th-your-api-key

두 개의 엔드포인트

POST
/videos/generations

비디오 생성 작업을 만들며, task ID를 반환합니다

GET
/videos/generations/{task_id}

작업 상태를 조회하며, 성공 시 video URL을 반환합니다

3모델 및 요금

모델 ID입력가격설명
doubao-seedance-2.0비디오 입력 없음$6.970/1M (1080p $7.727)플래그십 model, 최고 품질. 1080p 지원.
비디오 입력 포함$4.242/1M (1080p $4.697)비디오 입력이 포함된 플래그십, 비용 효율적.
doubao-seedance-2.0-fast비디오 입력 없음$5.606/1M빠른 model, 더 빠른 생성.
비디오 입력 포함$3.333/1M비디오 입력이 포함된 빠른 model, 가장 저렴함.

청구 세부정보:

  • 출력 video: 1M 토큰당 청구(토큰 수는 해상도와 재생 시간에 따라 달라짐)
  • 입력 이미지: 무료 (요금 없음)
  • 입력 video: 비디오 입력 포함 요율로 1M 토큰당 청구
  • 총 비용 = 총 소비 토큰 × 토큰당 요율(위 표 참조)

예: doubao-seedance-2.0 without video input (≤720p)으로 5초 비디오를 약 1M 토큰으로 생성하면 → 비용 ≈ $6.970

4요청 파라미터

파라미터타입필수 여부설명
modelstring필수Model ID, 예: "doubao-seedance-2.0"
promptstring필수video 설명 텍스트. 일반적으로 영어 프롬프트가 더 좋은 결과를 냅니다
durationnumber선택video 길이(초), 범위 4–15, 기본값 5
resolutionstring선택"480p", "720p", 또는 "1080p" (기본값 720p; 1080p는 doubao-seedance-2.0에서만 지원)
aspect_ratiostring선택화면 비율: "adaptive" (기본값), "16:9", "9:16", "1:1" 등
image_urlstring선택참조 이미지 URL (image-to-video)
image_urlsstring[]선택여러 참조 이미지 URL 배열
video_urlstring선택참조 video URL (video editing / video-to-video)
video_urlsstring[]선택여러 참조 video URL 배열 (최대 3개)
video_durationsnumber[]선택video별 길이(초) 배열, 예: [3, 5]
input_video_durationnumber선택총 입력 video 길이(초), video_durations의 대안
audio_urlstring선택참조 audio URL (배경음악 / SFX)
audio_urlsstring[]선택여러 참조 audio URL 배열 (최대 3개)
generate_audioboolean선택오디오를 생성할지 여부, 기본값 true
watermarkboolean선택워터마크를 추가할지 여부, 기본값 false
contentarray선택미디어 에셋 배열입니다. 각 항목: { type: "image_url", image_url: { url }, role }. 지원되는 role: first_frame (최대 1개), last_frame (최대 1개), reference_image, reference_video, reference_audio

5입력 제한

텍스트, 이미지, 비디오, 오디오를 입력으로 자유롭게 조합할 수 있습니다. 다음 제한 사항을 참고하세요:

이미지: 요청당 0–9개
비디오: 요청당 0–3개, 각 2–15초, 총 길이 ≤ 15초
오디오: 요청당 0–3개, 각 2–15초, 총 길이 ≤ 15초
❌ "Text + Audio only" 및 "Pure Audio" 입력은 지원되지 않습니다

지원 형식

  • 이미지 형식: JPEG, PNG, WebP, BMP, TIFF, GIF(각 최대 30MB)
  • 비디오 형식: MP4, MOV(H.264/H.265, 각 최대 50MB)
  • 오디오 형식: WAV, MP3(각 최대 15MB)
⚡ 팁: 과금에는 비디오 길이만 영향을 줍니다. 총 비용 = (입력 비디오 길이 + 출력 비디오 길이) × 요금. 입력 이미지는 무료입니다.

6전체 API 예제

가장 기본적인 사용법입니다. 텍스트로 장면을 설명해 비디오를 생성합니다.

bash
curl -X POST https://tokenhub.store/api/v1/videos/generations \
  -H "Authorization: Bearer th-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic slow motion, 4K quality",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "watermark": false
  }'

응답:

json
{
  "id": "xxxxxx-task-id",
  "object": "video.generation.task",
  "model": "doubao-seedance-2.0",
  "status": "queued",
  "created": 1719900000
}

비디오 생성은 비동기식입니다. 완료될 때까지 상태를 조회하세요.

bash
# Poll task status using the task_id from creation response
curl https://tokenhub.store/api/v1/videos/generations/YOUR_TASK_ID \
  -H "Authorization: Bearer th-your-api-key"

작업 진행 중:

json
{
  "id": "YOUR_TASK_ID",
  "object": "video.generation.task",
  "model": "doubao-seedance-2.0",
  "status": "running",
  "created": 1719900000
}

작업 완료(비디오 URL 수신됨):

json
{
  "id": "YOUR_TASK_ID",
  "object": "video.generation.task",
  "model": "doubao-seedance-2.0",
  "status": "succeeded",
  "created": 1719900000,
  "data": [
    {
      "video_url": "https://tokenhub-data.tos-cn-hongkong.volces.com/user_sd_file/YOUR_TASK_ID.mp4",
      "cover_image_url": "https://tokenhub-data.tos-cn-hongkong.volces.com/user_sd_file/YOUR_TASK_ID_cover.jpg"
    }
  ],
  "usage": {
    "video_duration": 5
  }
}
💡 권장 조회 간격: 3~5초마다. 상태 값: queued → waiting, running → generating, succeeded → done, failed → error

7Python 전체 예제

python
import requests
import time

API_BASE = "https://tokenhub.store/api/v1"
API_KEY = "th-your-api-key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Create video generation task
payload = {
    "model": "doubao-seedance-2.0",
    "prompt": "A majestic eagle soaring over snow-capped mountains, golden hour lighting, cinematic aerial shot",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "watermark": False
}

resp = requests.post(f"{API_BASE}/videos/generations", json=payload, headers=headers)
task = resp.json()
task_id = task["id"]
print(f"Task created: {task_id}, status: {task['status']}")

# Step 2: Poll for result
while True:
    resp = requests.get(f"{API_BASE}/videos/generations/{task_id}", headers=headers)
    result = resp.json()
    status = result["status"]
    print(f"Status: {status}")

    if status == "succeeded":
        video_url = result["data"][0]["video_url"]
        duration = result["usage"]["video_duration"]
        print(f"Video ready! Duration: {duration}s")
        print(f"URL: {video_url}")
        break
    elif status == "failed":
        print(f"Failed: {result.get('error', {}).get('message', 'Unknown error')}")
        break

    time.sleep(5)

8JavaScript / Node.js 전체 예제

javascript
const API_BASE = "https://tokenhub.store/api/v1";
const API_KEY = "th-your-api-key";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// Step 1: Create task
const createResp = await fetch(`${API_BASE}/videos/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "doubao-seedance-2.0",
    prompt: "A majestic eagle soaring over snow-capped mountains, cinematic aerial shot",
    duration: 5,
    resolution: "720p",
    aspect_ratio: "16:9",
    watermark: false,
  }),
});
const task = await createResp.json();
console.log("Task created:", task.id);

// Step 2: Poll for result
const poll = async () => {
  while (true) {
    const resp = await fetch(`${API_BASE}/videos/generations/${task.id}`, { headers });
    const result = await resp.json();
    console.log("Status:", result.status);

    if (result.status === "succeeded") {
      console.log("Video URL:", result.data[0].video_url);
      console.log("Duration:", result.usage.video_duration, "seconds");
      return result;
    }
    if (result.status === "failed") {
      console.error("Failed:", result.error?.message);
      return result;
    }
    await new Promise(r => setTimeout(r, 5000));
  }
};

await poll();

9이미지 투 비디오 Python 예제

python
import requests, time

API_BASE = "https://tokenhub.store/api/v1"
headers = {
    "Authorization": "Bearer th-your-api-key",
    "Content-Type": "application/json"
}

# Image-to-Video with a single reference image
payload = {
    "model": "doubao-seedance-2.0",
    "prompt": "The woman in the photo turns to face the camera and smiles warmly, her hair gently blowing in the wind",
    "duration": 5,
    "resolution": "720p",
    "image_url": "https://your-bucket.com/portrait.jpg",
    "watermark": False
}

resp = requests.post(f"{API_BASE}/videos/generations", json=payload, headers=headers)
task_id = resp.json()["id"]
print(f"Task: {task_id}")

# Poll for result
while True:
    r = requests.get(f"{API_BASE}/videos/generations/{task_id}", headers=headers).json()
    if r["status"] == "succeeded":
        print(f"Done: {r['data'][0]['video_url']}")
        break
    elif r["status"] == "failed":
        print(f"Error: {r.get('error', {}).get('message')}")
        break
    time.sleep(5)

10실제 인물 이미지-비디오

입력 이미지에 실제 인물이 포함되어 있으면 TokenHub이 실제 인물 생성을 지원하는 업스트림으로 요청을 자동 라우팅합니다. 클라이언트 변경은 필요하지 않습니다.

업스트림 콘텐츠 필터가 입력 이미지에서 실제 인물을 감지하면 자동으로 트리거됩니다.

요청 형식은 일반 이미지-비디오와 동일합니다 — 동일한 POST /v1/videos/generations 본문을 사용합니다.

가능한 응답 형식 2가지

  • 일반 경로: { "id": "cgt-...", "status": "queued" } (기존 동작)
  • 실제 인물 경로: { "id": "pat-...", "status": "queued" } — 추가 에셋 처리가 필요하므로 10~90초의 추가 지연을 예상하세요

GET 폴링도 동일합니다 — POST가 반환한 id로 /v1/videos/generations/{id}를 호출하고, status가 succeeded 또는 failed가 될 때까지 반복하세요. id 재작성은 서버 측에서 처리되며, 요청의 수명 동안에는 항상 동일한 id가 보입니다.

오류: unsupported_real_person_input

계정에 실제 인물 생성을 지원하는 provider가 구성되지 않은 경우 status 400으로 반환됩니다. 지원되는 provider를 활성화하려면 관리자에게 문의하세요.

오류: Asset 처리 시간 초과

업스트림 에셋 준비가 5분을 초과하면 GET 응답에서 status: failed로 반환됩니다. 요청을 안전하게 다시 시도할 수 있습니다.

전체 수명 주기 예시

pat-id는 클라이언트에서 해석할 수 없는 값입니다 — status가 바뀔 때까지 계속 폴링하세요.

bash
# POST
curl -X POST https://tokenhub.store/api/v1/videos/generations \
  -H "Authorization: Bearer $TH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "let her dance and spin",
    "duration": 8,
    "resolution": "480p",
    "content": [
      { "type": "image_url", "image_url": { "url": "https://example.com/portrait.png" }, "role": "first_frame" }
    ]
  }'
# → {"id":"pat-abc123","status":"queued"}

# GET (asset still uploading)
curl https://tokenhub.store/api/v1/videos/generations/pat-abc123 -H "Authorization: Bearer $TH_KEY"
# → {"id":"pat-abc123","status":"queued"}

# GET (upstream task running)
# → {"id":"pat-abc123","status":"running"}

# GET (complete — id stays pat-, video_url in data)
# → {"id":"pat-abc123","status":"succeeded","data":[{"video_url":"..."}]}

11프롬프트 팁

기본 구조

권장 형식: [주제] + [동작] + [환경/배경] + [카메라/스타일]

좋은 프롬프트 예시

  • "A young woman walking through a cherry blossom garden, petals falling in slow motion, soft natural lighting, cinematic 35mm film look"
  • "Close-up of hands pouring latte art into a ceramic cup, steam rising, warm cafe ambiance, shallow depth of field"
  • "Aerial drone shot of a winding river through autumn forest, golden and red leaves, morning mist, 4K cinematic"

참조 이미지/비디오 팁

  • 프롬프트에서 "image 1", "image 2", "video 1", "audio 1"을 사용해 에셋을 참조하세요
  • 시간 구간별 장면 내용을 지정하세요(예: "0-2s: xxx, 2-4s: xxx")
  • 시작/종료 프레임을 지정하세요(예: "첫 프레임은 image 1", "마지막 프레임은 image 2로 고정")
  • 카메라 구도 소스를 지정하세요(예: "video 1 POV를 전체에 사용")
  • 오디오 사용 방식을 지정하세요(예: "audio 1을 전체 배경 음악으로 사용")

  • 영문 프롬프트가 일반적으로 더 좋은 결과를 냅니다. 중국어도 지원됩니다
  • 더 구체적이고 생생한 설명일수록 결과가 좋아집니다
  • 지나치게 추상적인 설명은 피하세요(예: "좋은 비디오")
  • 카메라 관련 표현은 품질을 크게 향상시킵니다(슬로 모션, 클로즈업, 항공 샷, 트래킹 샷...)

12자주 묻는 질문

시작할 준비가 되셨나요?

TokenHub에 가입하고 지금 바로 Seedance 2.0 Video Generation API를 사용해 보세요

© 2026 TokenHub · Powered by ByteDance Seedance 2.0 · support@tokenhub.store