Seedance 2.0 API

비동기 작업 생성, 상태 폴링, 웹훅 및 크레딧 인식 청구를 통해 제품에 비디오 생성을 구축하세요.

API 키 생성API 대시보드
기본 URL
https://api.seedance2.ai
이 페이지 내용

소개

API를 사용하면 Seedance 2.0 비디오 생성 작업을 프로그래밍 방식으로 제출할 수 있습니다. 생성은 비동기식입니다. 작업을 생성하고 즉시 작업 ID를 받은 다음, 작업 엔드포인트를 폴링하거나 웹훅을 통해 완료된 비디오를 받으세요.

비동기 작업

폴링은 개발 및 간단한 통합에 적합합니다.

웹훅 준비

웹훅은 공격적인 폴링을 방지하고 작업이 종료 상태에 도달하면 서비스에 알리기 때문에 프로덕션 환경에 권장됩니다.

크레딧 인식

크레딧은 제출 시 예약됩니다. 성공적인 작업에는 해당 예약에서 요금이 청구됩니다. 실패하거나 시간 초과된 작업은 자동으로 환불됩니다.

인증

대시보드에서 API 키를 생성하고 모든 요청에 Bearer 토큰으로 전송합니다. 전체 키는 생성 시 한 번만 표시됩니다.

Authorization: Bearer sk_live_xxxxxxxx
sk_live_

프로덕션 트래픽에는 sk_live_ 키를 사용하십시오.

sk_test_

동일한 API 계약으로 샌드박스 통합 테스트에는 sk_test_ 키를 사용하십시오.

401

누락되었거나, 유효하지 않거나, 취소된 키는 HTTP 401과 함께 invalid_api_key를 반환합니다.

빠른 시작

먼저 작업을 제출하십시오. 작업이 허용되면 한 가지 결과 전달 방법을 선택하십시오. 작업 엔드포인트를 폴링하거나 웹훅을 통해 최종 결과를 받으십시오.

작업 제출

비동기 비디오 작업을 생성하고 즉시 작업 ID를 받으십시오.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'
결과 옵션: 폴링

통합에서 명시적인 폴링을 선호하는 경우 작업 상태 엔드포인트를 가져옵니다.

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"
결과 옵션: 웹훅

작업 제출 시 callback_url을 전달한 다음, 완료 또는 실패 콜백을 수신하고 자체 작업 기록을 업데이트합니다.

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

비디오 작업 생성

POST /v1/videos/generations를 사용하여 비디오 작업을 생성합니다. 요청 본문에는 최상위 모델, 선택적 callback_url, 그리고 프롬프트 및 생성 설정을 포함하는 input 객체가 있습니다.

POST
/v1/videos/generations
curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

생성 모드

generation_type은 허용되는 미디어 입력과 모델이 이를 해석하는 방식을 제어합니다.

모드필수 미디어선택적 미디어참고
text-to-video프롬프트duration, aspect_ratio, resolution, seed텍스트 프롬프트만. image_urls, video_urls, audio_urls는 필요하지 않습니다.
image-to-video프롬프트 + image_urls 배열 (1-2개의 이미지 URL)duration, aspect_ratio, resolution, seedimage_urls는 배열이어야 합니다. 첫 번째 프레임에 1개의 이미지 URL을 제공하거나, 첫 번째 및 마지막 프레임에 2개의 이미지 URL을 제공하십시오. 비디오 및 오디오는 무시됩니다.
reference-to-video프롬프트 + 최소 하나의 이미지 또는 비디오자료 제한 내의 이미지, 비디오 및 오디오오디오는 텍스트와 단독으로 사용될 수 없습니다. 오디오를 제공할 때 최소 하나의 이미지 또는 비디오를 추가하십시오.
text-to-video

프롬프트가 유일한 크리에이티브 입력인 경우 텍스트-투-비디오를 사용하십시오. (text-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'
image-to-video

input.image_urls가 1-2개의 이미지 URL을 포함하는 배열인 경우 이미지-투-비디오를 사용하십시오. 하나의 URL은 첫 번째 프레임을 설정하고, 두 개의 URL은 첫 번째 및 마지막 프레임을 설정합니다. 이 모드에서는 비디오 및 오디오 참조가 무시됩니다. (image-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'
reference-to-video

참조 이미지, 비디오 및 오디오를 사용하여 보다 풍부한 방향 지시를 위해 참조-투-비디오를 사용하십시오. 오디오는 텍스트와 단독으로 사용될 수 없습니다. 오디오를 제공할 때 최소 하나의 이미지 또는 비디오를 포함하십시오. (reference-to-video)

자료 제한

  • 최대 9개의 참조 이미지
  • 최대 3개의 참조 비디오, 총 재생 시간 15초 이하
  • 최대 3개의 참조 오디오, 총 재생 시간 15초 이하
  • 모든 유형에 걸쳐 총 최대 12개의 자료

지원되는 입력 조합

텍스트 + 이미지
텍스트 + 비디오
텍스트 + 이미지 + 비디오
텍스트 + 이미지 + 오디오
텍스트 + 비디오 + 오디오
텍스트 + 이미지 + 비디오 + 오디오
curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "1080p"
    }
  }'

요청 매개변수

매개변수 이름, 열거형 값, 엔드포인트 경로 및 예시는 API 계약의 일부입니다. 아래 설명은 각 필드가 어떻게 작동하는지 설명합니다.

헤더

헤더필수설명예시
Authorization예요청을 인증하는 데 사용되는 Bearer API 키.Bearer sk_live_xxx
Content-Type예모든 쓰기 요청은 JSON을 사용합니다.application/json

최상위 필드

필드유형필수기본값범위 / 열거형모드예시
model

생성에 사용되는 모델 변형.

string예-seedance-2-0 | seedance-2-0-fast모두seedance-2-0
callback_url

작업 완료 및 실패 콜백을 수신하는 HTTPS 엔드포인트.

string아니요-HTTPS URL, 사설 네트워크 없음모두https://your-domain.com/hook
input

생성 설정 및 미디어 참조.

object예--모두-

input.* 필드

필드유형필수기본값범위 / 열거형모드예시
input.prompt

생성할 비디오를 설명하는 텍스트 프롬프트.

string예-비어 있지 않은 텍스트모두a cat surfing
input.generation_type

생성 모드. 기본값은 텍스트-투-비디오. (text-to-video)

string아니요text-to-videotext-to-video | image-to-video | reference-to-video-image-to-video
input.image_urls

공개적으로 접근 가능한 이미지 URL. 이미지-투-비디오의 경우 첫 번째 프레임에 1개의 이미지를 보내거나 첫 번째 및 마지막 프레임에 2개의 이미지를 보냅니다. 참조-투-비디오의 경우 최대 9개의 이미지를 시각적 참조로 보냅니다. (image-to-video) (reference-to-video)

string[]조건부[]이미지-투-비디오: 1 또는 2개의 이미지. 참조-투-비디오: 최대 9개의 이미지. (image-to-video) (reference-to-video)image-to-video / reference-to-video["https://.../a.jpg"]
input.video_urls

참조-투-비디오에만 사용되는 공개적으로 접근 가능한 참조 비디오. 최대 3개의 비디오 파일을 보낼 수 있으며, 결합된 재생 시간은 15초 이하여야 합니다. (reference-to-video)

string[]아니요[]최대 3개의 비디오. 결합된 비디오 길이는 15초 이하여야 합니다.reference-to-video[]
input.audio_urls

참조-투-비디오에만 사용되는 공개적으로 접근 가능한 참조 오디오 파일. 최대 3개의 오디오 파일을 보낼 수 있으며, 결합된 재생 시간은 15초 이하여야 합니다. (reference-to-video)

string[]아니요[]최대 3개의 오디오 파일. 결합된 오디오 길이는 15초 이하여야 합니다.reference-to-video[]
input.duration

출력 비디오 길이(초).

int아니요54-15초모두5
input.aspect_ratio

출력 종횡비. adaptive는 서비스가 최상의 비율을 추론하도록 합니다.

string아니요adaptive16:9 | 4:3 | 1:1 | 3:4 | 9:16 | 21:9 | adaptive모두16:9
input.resolution

출력 해상도 등급.

string아니요720p480p | 720p | 1080p모두720p
input.generate_audio

지원되는 경우 모델이 오디오를 생성해야 하는지 여부.

boolean아니요truetrue | false모두true
input.watermark

워터마크를 추가할지 여부.

boolean아니요falsetrue | false모두false
input.web_search

지원되는 경우 웹 검색 증강을 허용할지 여부.

boolean아니요falsetrue | false모두false
input.return_last_frame

사용 가능한 경우 마지막 프레임 URL을 반환할지 여부.

boolean아니요falsetrue | false모두false
input.seed

결정론적 시드. 무작위 시드의 경우 -1을 사용합니다.

int아니요-1-1 또는 0-4294967295모두-1

크레딧은 해상도, 재생 시간, 모델, 그리고 참조-투-비디오에 비디오 참조가 포함되는지 여부에 따라 달라집니다. 생성 응답으로 반환되는 크레딧 값은 해당 작업에 대해 실제로 예약된 양입니다. (reference-to-video)

크레딧 가격 보기

응답

이것은 POST /v1/videos/generations의 성공 응답입니다. 작업이 수락되었고 크레딧이 예약되었음을 의미합니다. 반환된 taskId를 사용하여 GET /v1/tasks/:id를 폴링하거나 완료 또는 실패 콜백과 일치시키십시오.

POST /v1/videos/generations 성공 응답

{
  "taskId": "3f2aK9mR...",
  "credits": 60
}

작업 상태 확인

현재 작업 상태를 검색하려면 GET /v1/tasks/:id를 사용하십시오. 10초마다 한 번 이상 폴링하지 마십시오. 프로덕션 시스템의 경우 웹훅을 선호합니다.

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

완료된 작업 응답

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

실패한 작업 응답

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "refunded",
  "credits": 60,
  "failed_reason": "provider_failed"
}
값의미
status=queued접수되었고 제출 또는 처리 대기 중입니다.
status=generating공급자가 생성을 처리 중입니다.
status=completed비디오가 완료되었고 data.results에 결과 URL이 포함되어 있습니다.
status=failed생성 실패 또는 시간 초과되었습니다.
billing_status=reserved작업이 진행 중인 동안 크레딧이 예약됩니다.
billing_status=charged작업이 성공적으로 완료되었고 예약이 결제되었습니다.
billing_status=refunded작업이 실패하거나 시간 초과되어 크레딧이 자동으로 반환되었습니다.
billing_status=refund_failed환불 거래가 실패하여 수동 처리가 필요합니다.

video_expires_at 이후에는 data.results가 비어 있습니다. 유효 기간이 끝나기 전에 파일을 다운로드하고 저장하십시오.

웹훅

callback_url이 존재하는 경우, Seedance는 작업이 완료되거나 실패할 때 엔드포인트를 호출하고 최종 결과를 설명하는 JSON 데이터를 보냅니다. 엔드포인트가 2xx가 아닌 응답을 반환하거나 15초 이내에 응답하지 않으면, 최대 5번까지 재전송됩니다. 재전송은 동일한 작업 ID를 재사용하므로 ID별로 중복 제거하십시오. 콜백 데이터를 안전하게 기록하는 즉시 200 응답을 반환하십시오.

작업 완료 콜백

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

작업 실패 콜백

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 60
  }
}
export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

콜백 데이터 형식을 검증하고, ID별로 중복 제거하고, 자체 작업 기록을 업데이트하고, 신속하게 응답하십시오.

callback_url은 HTTPS여야 하며 사설, 루프백 또는 링크-로컬 네트워크 범위로 지정해서는 안 됩니다.

오류

POST /v1/videos/generations 및 GET /v1/tasks/:id는 API 요청 자체에 실패할 때(예: 유효하지 않은 매개 변수, 유효하지 않은 API 키, 불충분한 크레딧, 속도 제한 또는 작업을 찾을 수 없음) 이 오류 형식을 반환합니다. 일부 오류에는 상황에 따라 required, available 또는 retry_after와 같은 추가 필드가 포함됩니다.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 60,
    "available": 12
  }
}
코드HTTP의미재시도?
invalid_request400누락되었거나 유효하지 않은 매개변수.아니요, 요청을 수정하십시오.
invalid_api_key401API 키가 누락되었거나, 유효하지 않거나, 취소되었습니다.아니요, 유효한 키를 사용하십시오.
insufficient_credits402크레딧이 부족합니다. 작업이 허용되거나 청구되지 않습니다.재충전 후.
forbidden403API 키에 필요한 범위가 부족합니다.아니요.
not_found404작업이 존재하지 않거나 키 소유자에게 속하지 않습니다.아니요.
rate_limited429요청 속도 초과.예, Retry-After를 따르십시오.
internal_error500서버 오류.예, 나중에 다시 시도하십시오.

속도 제한

속도 제한은 슬라이딩 윈도우 방식으로 API 키당 적용됩니다. 생성은 기본적으로 분당 60개의 요청으로 제한됩니다. 상태 쿼리는 더 관대합니다. HTTP 429 응답에는 Retry-After가 포함됩니다.

생성

60/min

상태 쿼리

더 관대함

429 헤더

Retry-After

청구 및 크레딧

API는 제출 시 예약, 성공 시 청구, 실패 시 환불 정책을 사용합니다. 대시보드 사용 페이지에는 API 크레딧 기록, 작업 로그 및 시간 기반 사용 통계가 표시됩니다.

예약됨

작업이 수락되면 크레딧이 확인되고 예약됩니다.

청구됨

완료된 작업은 기존 예약을 결제합니다.

환불됨

실패하거나 시간 초과된 작업은 예약된 크레딧을 자동으로 반환합니다.

대시보드에서 사용량 검사

API 로그, 작업 타임라인, 크레딧 기록 및 시간 기반 사용 지표를 확인하십시오.

API 로그