Seedance 2.5를
내 제품 안으로.

몇 번의 요청으로 첫 동영상을 만드세요.

서버 환경 변수 SEADANCE_API_KEY에 키를 저장하세요. 이번 동영상에 사용할 고유한 SEADANCE_REQUEST_KEY를 설정하고(예: uuidgen으로 생성), 재시도할 때도 이 값을 유지하세요. 계정에 충분한 크레딧이 있는지 확인하세요. 이 예제는 5초 720p 동영상에 350 크레딧을 선차감합니다. 반환된 id를 저장해 작업 상태를 조회하세요.

export SEADANCE_API_KEY="sd_live_your_key"
# Keep this value for retries; choose a new value for a new video.
export SEADANCE_REQUEST_KEY="${SEADANCE_REQUEST_KEY:-$(uuidgen)}"

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos" \
  -H "Authorization: Bearer $SEADANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SEADANCE_REQUEST_KEY" \
  --data '{
  "model": "seedance-2.5",
  "mode": "text-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

이 문서는 자동으로 생성을 실행하지 않습니다. 생성 요청을 보내면 계정의 크레딧이 사용됩니다.

서버에서 인증하세요.

모든 API 호출에는 Authorization: Bearer sd_live_…가 필요합니다. 키를 브라우저, 모바일 앱, 공개 저장소 또는 클라이언트 코드에 포함하지 마세요. 전체 키는 한 번만 표시되며, API 대시보드에서 폐기할 수 있습니다.

기본 키 권한은 업로드 및 생성용 videos:write, 모델 및 작업 상태 조회용 videos:read, 크레딧 조회용 account:read입니다. 계정의 접근 설정과 한도는 모든 키에 적용됩니다.

동영상 생성 작업을 만드세요.

Content-Type: application/json을 사용하고 생성할 동영상마다 고유한 Idempotency-Key를 지정하세요. 서버가 상위 제공업체의 작업을 접수하는 데 시간이 걸릴 수 있습니다. 연결이 시간 초과되면 동일한 본문과 키로 다시 시도하세요. HTTP 202는 접수되었다는 뜻이며 완료되었다는 뜻이 아닙니다. Idempotency-Key는 공백 없는 출력 가능한 ASCII 문자 1~128자를 허용합니다.

이 필드들을 통해 Seedance 2.5의 텍스트 입력, 시작·끝 프레임, 멀티모달 참조, 동영상 편집 및 연장 기능을 사용할 수 있습니다. 현재 사용 가능한 기능과 요금은 GET /models 응답을 기준으로 확인하세요.

{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "firstFrameUrl": "YOUR_UPLOADED_PUBLIC_OBJECT_URL"
}

{
  "model": "seedance-2.5",
  "mode": "reference-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "referenceImageUrls": [
    "YOUR_UPLOADED_IMAGE_URL"
  ],
  "referenceVideoUrls": [
    "YOUR_UPLOADED_VIDEO_URL"
  ]
}

한 번 업로드하고 URL로 참조하세요.

POST /uploads에 fileName, contentType, size(바이트), kind(image, video 또는 audio)를 제출하세요. expiresAt 전에 requiredHeaders를 사용해 원본 파일 바이트를 uploadUrl로 PUT 업로드합니다. 업로드가 성공하면 생성 요청에 publicObjectUrl을 사용하세요. 자료는 동일한 계정에 속해야 하며, 임의의 외부 URL과 base64 입력은 허용되지 않습니다.

// Node.js 20+ · upload once, then use publicObjectUrl
import { readFile } from "node:fs/promises";

const bytes = await readFile("./first-frame.jpg");
const signed = await fetch("https://seedance3ai.dev/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEADANCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fileName: "first-frame.jpg", contentType: "image/jpeg",
    size: bytes.length, kind: "image",
  }),
});
const upload = await signed.json();
if (!signed.ok) throw new Error(JSON.stringify(upload));
const stored = await fetch(upload.uploadUrl, {
  method: "PUT", headers: upload.requiredHeaders, body: bytes,
});
if (!stored.ok) throw new Error("Upload failed");
console.log(upload.publicObjectUrl);
// Use this URL as firstFrameUrl in an image-to-video request.

신고한 파일 크기와 콘텐츠 유형은 실제 업로드 파일과 일치해야 합니다. 업로드 URL이 만료되면 새로 요청하세요. 생성 전에 자료의 길이, 크기, 형식을 검증합니다.

완료될 때까지 작업을 확인하세요.

GET /videos/:id는 현재 작업 상태를 반환합니다. 5~10초마다 조회하고 succeeded 또는 failed가 되면 중지하세요. Retry-After가 있으면 안내된 시간만큼 기다리세요. 본인 계정에서 API로 만든 작업만 조회할 수 있습니다. 현재 연동 방식은 폴링입니다.

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

{
  "id": "a1b2c3d4-1234-4567-8901-abcdef123456",
  "status": "succeeded",
  "credits_reserved": 350,
  "created_at": "2026-10-27T00:00:00.000Z",
  "output": {
    "url": "https://your-result-host.example/video.mp4"
  },
  "error": null,
  "refund_status": "not_applicable"
}

동영상이 준비되기 전에는 output이 null입니다. 실패한 작업에는 error가 포함되며, refund_status로 크레딧 환불 상태를 확인할 수 있습니다. 성공한 결과는 바로 다운로드하세요. 동영상을 삭제해도 요청은 초기화되지 않습니다. 같은 Idempotency-Key로 다시 보내면 410 video_deleted가 반환되며 다시 생성되지 않습니다.

연동 전에 크레딧 비용을 확인하세요.

API 생성은 웹사이트와 동일한 계정 크레딧 및 Seedance 2.5 요율을 사용합니다. 요청이 접수되면 크레딧을 선차감하고, 생성 실패 시 일회성 크레딧 잔액으로 돌려드립니다. 작업 생성 전 검증에 실패한 경우에는 과금 대상 동영상이 생성되지 않습니다.

비용 = 출력 길이 × 출력 단가 + 참조 동영상 길이 × 참조 단가입니다. 참조 동영상 길이는 서버에서 측정하며, 총 길이를 초 단위로 내림하여 계산합니다. 기본 오디오 생성은 포함되어 있습니다. 예를 들어 5초 720p 동영상은 350 크레딧이며, 5초 참조 동영상을 함께 사용하면 600 크레딧입니다.

curl --fail-with-body "https://seedance3ai.dev/api/v1/models" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

curl --fail-with-body "https://seedance3ai.dev/api/v1/credits" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

API 대시보드에서 사용 가능한 크레딧, 요청 기록, 계정 한도를 확인하세요. 동일한 계정으로 웹사이트 요금 페이지에서 크레딧을 충전하면 됩니다. 별도의 API 잔액이나 API 충전 엔드포인트는 없습니다. 사용 가능한 크레딧이 충분하면 활성 구독이 없어도 호출할 수 있습니다. 구독 만료 및 일회성 크레딧 규칙은 웹사이트와 동일합니다.

크레딧을 충전해도 API 요청 빈도, 동시 작업 수, 일일 한도가 늘어나거나 비활성화된 계정이 다시 활성화되지는 않습니다. 일일 한도에는 실패 후 환불된 크레딧을 포함한 모든 선차감 크레딧이 집계되며, UTC 00:00에 초기화됩니다. 더 높은 한도가 필요하면 지원팀에 문의하세요.

안전하게 재시도하고 중복 과금을 피하세요.

생성할 동영상마다 하나의 Idempotency-Key를 사용하고, 결과가 확정될 때까지 정확히 동일한 요청 본문과 함께 보관하세요. 새 키는 새 생성 요청을 의미합니다. 오류 응답에는 error.code, error.message, request_id가 포함됩니다. 지원팀에 문의할 때 요청 ID를 함께 보내주세요.