Seedance API

본 API를 사용하면 프로그램 방식으로 Seedance 2.5 및 Seedance 2.0 비디오 생성 작업을 처리할 수 있습니다. 권장 모델인 Seedance 2.5는 텍스트 투 비디오, 첫 프레임 또는 첫 프레임 및 마지막 프레임 기반의 이미지 투 비디오, 그리고 멀티모달 참조 투 비디오 생성을 지원합니다. 생성 프로세스는 비동기 방식으로 진행됩니다. 작업을 생성하면 즉시 작업 ID(task ID)가 반환되며, 작업 엔드포인트를 폴링하거나 웹훅을 수신하여 완료된 비디오를 받아볼 수 있습니다.

대시보드에서 API 키를 생성한 후 모든 요청에 Bearer 토큰으로 포함하여 전송하세요. 전체 API 키는 생성할 때 딱 한 번만 표시됩니다.

Authorization: Bearer sk_live_xxxxxxxx

먼저 비디오 생성 작업을 요청하세요. 작업이 정상적으로 접수되면, 결과물을 전달받을 방식을 선택합니다. 작업 엔드포인트를 폴링하거나 웹훅을 통해 최종 결과를 수신할 수 있습니다.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

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

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를 호출하여 비디오 생성 작업을 생성합니다. 요청 바디의 최상위 레벨에는 model 정보와 선택 사항인 callback_url, 그리고 prompt 및 생성 설정을 포함한 input 객체가 들어갑니다.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

generation_type 매개변수는 허용되는 미디어 입력값의 종류와 모델이 이를 해석하는 방식을 제어합니다.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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"
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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": "720p"
    }
  }'

매개변수 이름, Enum 값, 엔드포인트 경로, 예시 등은 고정된 API 규격입니다. 아래에서 각 필드의 상세 동작 방식을 확인할 수 있습니다.

POST /v1/videos/generations 요청이 성공적으로 접수되었을 때 반환되는 응답입니다. 이는 작업이 성공적으로 큐에 등록되고 크레딧 예약이 완료되었음을 의미합니다. 반환된 taskId를 사용해 GET /v1/tasks/:id 엔드포인트를 호출하여 상태를 확인하거나, 이후 수신할 웹훅 콜백 데이터와 비교 매칭할 수 있습니다.

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

현재의 작업 상태를 확인하려면 GET /v1/tasks/:id 엔드포인트를 사용하세요. 너무 빈번한 호출을 피하기 위해 폴링 주기는 최소 10초 이상으로 유지해야 합니다. 실제 프로덕션 서비스를 연동할 때는 웹훅 사용을 권장합니다.

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

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

요청 시 callback_url을 제공한 경우, Seedance는 작업 완료 또는 실패 시 지정된 엔드포인트로 최종 결과물이 담긴 JSON 데이터를 전송합니다. 만약 콜백 수신 서버가 2xx 계열 이외의 응답을 반환하거나 15초 이내에 응답하지 않을 경우, 최대 5회까지 재시도를 수행합니다. 이때 재시도 요청도 동일한 task id를 유지하므로 중복 데이터 수신 처리에 유의해 주세요. 콜백 데이터를 성공적으로 기록했다면 즉시 200 OK 응답을 반환하는 것이 좋습니다.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

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 });
}

잘못된 매개변수 입력, 유효하지 않은 API 키 사용, 크레딧 부족, 속도 제한 초과, 없는 작업 조회 등 API 요청 자체가 실패한 경우 POST /v1/videos/generations 및 GET /v1/tasks/:id는 아래 규격의 에러 응답을 반환합니다. 일부 에러 상황에 따라 required, available, retry_after와 같은 추가 정보 필드가 포함될 수 있습니다.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

API 키별로 슬라이딩 윈도우 방식의 속도 제한이 적용됩니다. 비디오 생성 요청은 기본 분당 100회로 제한되며, 상태 조회(폴링) 요청은 이보다 더 유연하게 허용됩니다. HTTP 429 응답 수신 시, Retry-After 헤더 정보를 참고하세요.

API 크레딧 결제는 '요청 시 예약, 성공 시 실제 차감, 실패 시 환불' 정책을 따릅니다. 대시보드의 사용량 페이지에서 상세한 API 크레딧 사용 내역, 작업 로그 및 기간별 이용 통계를 직관적으로 확인할 수 있습니다.