문서

Seevio API로 개발하기

귀사의 제품에 비디오 생성 기능을 추가해 보세요. 모델을 선택하고 요청을 전송한 후, 폴링 방식이나 웹훅을 통해 결과물을 받아볼 수 있습니다.

API 키 생성 API 대시보드

모델 선택

각 모델별 레퍼런스 문서에는 상세한 파라미터 정보, 요금, 실제 예시가 포함되어 있습니다. 단일 모델 문서 페이지 안에서 모든 연동 작업을 마칠 수 있습니다.

Seedance 2.5

480p · 720p · 1080p

4~30초

모델 문서 보기

Seedance 2.0

480p · 720p · 1080p · 4k

4~15초

모델 문서 보기

Seedance 2.0 Fast

480p · 720p

4~15초

모델 문서 보기

Seedance 2.0 Mini

480p · 720p

4~15초

모델 문서 보기

인증

API 대시보드에서 API 키를 생성하세요. 생성된 전체 API 키 값은 최초 1회만 노출됩니다. 키를 서버 측에 안전하게 보관하고, 모든 API 요청 시 Bearer 토큰으로 포함하여 전송해 주세요.

API 키 생성 API 대시보드

기본 URL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

아래 예시 코드를 실행하기 전에 SEEVIO_API_KEY 환경 변수를 설정해야 합니다. JavaScript 예시는 Node.js 기반 서버 환경에서 실행되며, Python 예시는 requests 패키지를 사용합니다.

빠른 시작

이 예시는 Seedance 2.5를 사용하여 5초 분량의 720p 비디오를 생성합니다. 전체 생성 모드와 파라미터 제약 사양을 확인하시려면 개별 모델 문서를 확인해 주세요.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

작업 생성 응답 예시

위의 요청이 수락되면 API는 이 JSON 응답을 반환합니다. taskId는 후속 상태 조회에 사용되는 작업 식별자이며, credits는 이 작업에 예약된 크레딧 수입니다. 이 응답은 비디오 생성 완료가 아닌 작업이 성공적으로 생성되었음을 확인하는 것입니다. 비디오 결과를 받으려면 작업 상태를 폴링하거나 웹훅(Webhook)을 사용해야 합니다.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

작업 조회

GET https://api.seevio.ai/v1/tasks/{taskId}

예시에 작성된 ID 대신 작업 생성 시 전달받은 taskId를 사용해 주세요. 조회를 요청한 API 키에 귀속된 작업만 반환되며, 소유자가 다르거나 존재하지 않는 ID를 사용해 조회하면 HTTP 404 오류가 발생합니다.

클라이언트 사이드에서 초기 확인 시에는 10~20초 간격으로 폴링을 진행하는 것을 권장하며, HTTP 429 오류가 발생하는 경우 폴링 주기를 더 늘리고 작업 상태가 completed 또는 failed가 되면 조회를 멈추십시오. 프로덕션 환경에서는 웹훅 방식을 적극 권장합니다. 아래의 예시 코드는 각각 단발성 1회 조회를 수행하는 예시입니다.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

상태	설명 및 제약 조건
`queued`	작업이 접수되어 처리 대기 중입니다.
`generating`	비디오 생성이 진행 중입니다.
`completed`	작업이 최종 완료되었습니다. 만료되기 전에 data.results에서 결과물 비디오를 다운로드하세요.
`failed`	최종 실패 처리되었습니다. failed_reason과 billing_status 필드를 확인하세요.

필드	타입	설명 및 제약 조건
`id`	string	작업 식별자입니다. 작업 생성 응답에서 받은 taskId 필드 값과 동일합니다.
`created_at`	number	작업이 생성된 Unix 타임스탬프(초 단위)입니다.
`model`	string	이 작업에 사용된 퍼블릭 모델 ID입니다.
`billing_status`	string	정산 상태를 나타내며, 값은 reserved(가예약), charged(실제 결제), refunded(환불 완료), refund_failed(환불 실패) 중 하나입니다.
`credits`	number	이 작업에 가예약된 크레딧입니다. 이 금액은 환불 처리 이후에도 이력 보존을 위해 그대로 남아 있으며, 최종 결제 결과는 billing_status의 값을 통해 파악해야 합니다.
`failed_reason`	string \| null	실패한 작업의 구체적인 오류 원인입니다. 정상적으로 처리된 작업의 경우 null이 반환됩니다. 실패 상태의 조회 응답에는 data 필드가 포함되지 않습니다.
`data`	object	작업 실패가 아닌 경우에 생성되는 객체입니다. 최종 출력 파일 및 상세 처리 내역을 포함합니다.
`data.results`	string[]	비디오 파일 다운로드 URL의 배열입니다. 작업이 완료되기 전이나 비디오가 만료된 이후에는 빈 배열로 반환됩니다.
`data.video_expires_at`	string \| null	생성된 비디오 파일의 만료 일시를 나타내는 ISO 8601 타임스탬프 형식입니다. 결과물이 제공되기 전에는 null로 표시됩니다. 만료 시간 전에 결과물을 다운로드하여 자체 저장소에 보관해 주세요.
`data.last_frame_url`	string \| null	추가로 요청한 마지막 프레임의 이미지 URL입니다. 제공 준비가 완료되기 전까지는 null 상태로 표시됩니다.
`data.processing_time`	number \| null	제공사에서 실제 작업 생성에 소요된 시간(초 단위)입니다. 아직 완료되지 않은 등의 상태에서는 null로 반환될 수 있습니다.

작업 완료: 비디오 결과가 포함된 조회 응답

조회 결과 status=completed로 표시되면 비디오 생성이 완료된 상태입니다. data.results에서 비디오 URL을 확인하고, data.video_expires_at 이전에 다운로드하세요. billing_status=charged는 예약된 크레딧이 최종 차감되었음을 나타냅니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

작업 실패: 오류 원인 및 결제 상세 정보가 포함된 조회 응답

조회 결과 status=failed로 표시되면 비디오 생성이 실패한 상태입니다. 구체적인 실패 원인은 failed_reason에서, 환불 결과는 billing_status에서 확인하세요. 이 예시의 refunded는 크레딧이 정상적으로 반환되었음을 나타냅니다. credits는 처음 예약된 금액을 유지하며, 응답에 data는 포함되지 않습니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

웹훅

실제 서비스 연동 시에는 작업을 생성할 때 callback_url을 함께 전달하는 것이 좋습니다. 모든 모델 레퍼런스 문서에서 콜백 페이로드 구조와 수신 서버 구현 예시를 제공합니다.

작업 생성 시 callback_url 파라미터를 추가하면, 비디오 생성이 완료되거나 실패했을 때 지정하신 주소로 JSON POST 요청을 보내드립니다. 콜백 수신 후 15초 이내에 2xx 응답을 반환해 주셔야 합니다. 콜백 전송에 실패하는 경우 재시도가 진행되므로, 수신부에서는 task ID를 기준으로 중복 처리가 되지 않도록 멱등성을 보장하도록 구현해 주세요.

콜백 엔드포인트는 JSON 요청 본문(Content-Type: application/json)을 포함한 POST 요청을 수락해야 합니다.

콜백을 포함하여 작업 생성하기

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

웹훅 페이로드 형식은 일반 작업 조회 응답과 소폭 다릅니다. billing_status 및 credits 필드가 최상위에 제공되지 않으며, 실패한 작업의 경우 구체적인 사유가 data.failed_reason 및 data.credits_refunded 내부에 위치하게 됩니다. 웹훅의 created_at 필드는 이벤트가 생성된 시각의 Unix 타임스탬프(초 단위)를 의미합니다.

작업 완료: 콜백 페이로드 성공

생성에 성공하면 콜백에 status=completed가 포함됩니다. id로 작업을 식별하고 data.results에서 비디오 URL을 가져오세요. 결과물은 data.video_expires_at 이전에 다운로드하여 저장해야 합니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

작업 실패: 콜백 페이로드 실패

생성에 실패하면 콜백에 status=failed가 포함됩니다. id로 작업을 식별하고, data.failed_reason에서 실패 원인을, data.credits_refunded에서 환불된 크레딧 수량을 확인하세요.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

수신 서버 구현 예시

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

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

이 Next.js 예시는 JSON 콜백 본문을 읽고 완료 및 실패한 작업을 직접 처리합니다. 실제 애플리케이션에서는 데이터 영속성과 작업 ID 중복 제거 기능을 추가하세요. 콜백 응답을 보내기 전에 시간이 오래 걸리는 작업은 큐(queue)에 대기시키는 것이 좋습니다.

오류 처리

API 요청 처리 중 오류가 발생하면 HTTP 상태 코드와 함께 오류 정보 객체(error)가 전달되며 해당 객체에는 오류 코드(code)와 에러 메시지(message)가 들어 있습니다. 작업 생성이 성공적으로 접수된 후에도 실제 비디오 생성 과정에서 실패가 발생할 수 있으므로, 주기적으로 조회하거나 실패 콜백 처리를 구현해 두어야 합니다.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	필드	해결 방법
400	`invalid_request`	전송한 JSON 형식의 결함 여부, 프롬프트 누락, 파라미터 값의 유효 범위를 확인하거나 미디어 파일의 HTTPS 다운로드 주소가 정상인지 확인 후 다시 시도하세요.
401	`invalid_api_key`	전달된 Bearer 토큰 및 API 키가 활성화 상태인지 확인해 주세요.
402	`insufficient_credits`	계정에 크레딧을 추가로 충전하거나, 생성 사양을 낮추어 예상 작업 크레딧 소비량을 감축하십시오. 응답 메시지에 필요한 금액과 현재 잔액이 포함되어 안내될 수 있습니다.
403	`forbidden`	오류 메시지에 안내된 계정 수준의 제한 사항을 확인해 주세요.
404	`not_found`	검색에 사용한 작업 ID를 다시 확인해 주세요. 요청한 API 키를 소유한 유저가 생성한 작업만 조회가 가능합니다.
429	`rate_limited`	응답 헤더로 전달된 Retry-After 지정 시간만큼 일시 정지 후 다시 전송을 시도해 주세요.
500	`internal_error`	반환된 에러 메시지 및 API 세부 로그를 자세히 살펴보세요. 동일 요청 재시도 시 불필요하게 가예약 및 청구 처리가 중복 발생할 위험이 있으므로 재시도 시 주의해 주십시오.