문서 바로가기
목차

Seedance 2.5 Flash

텍스트, 첫/마지막 프레임 이미지, 멀티모달 레퍼런스를 사용하여 Seedance 2.5 Flash(으)로 비디오를 생성합니다. 이 페이지에서는 이 모델의 전체 요청-응답 워크플로우를 다룹니다.

API 모델 ID: seedance-2-5-flash

비디오 생성은 비동기 방식으로 처리됩니다. 작업을 생성할 때 반환되는 taskId를 저장한 후, 해당 ID로 진행 상태를 조회하거나 웹훅으로 결과를 수신하세요.

지원 기능

Seedance 2.5 Flash는 480p와 720p를 지원하며 기본값은 720p입니다. 1080p, 4k, Draft 미리보기 및 Draft를 이용한 최종 영상 생성은 지원하지 않습니다.
기능지원하는 값
출력 해상도480p · 720p
출력 재생 시간4~30초
화면 비율16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive
참조 이미지이미지 최대 30장
참조 비디오동영상 최대 10개
참조 오디오 파일오디오 파일 최대 10개
전체 참조 미디어 합계참조 파일 총 50개까지
비디오/오디오 그룹별 총 재생 시간30초
seed-1부터 2147483647까지
레퍼런스 비디오 모드에서는 duration=-1 설정도 가능합니다. 자세한 내용은 아래의 비디오 편집 기능 및 요금 안내를 참고해 주세요. image-to-video 모드에서는 adaptive 화면 비율만 지원하므로 이 필드를 생략하거나 adaptive로 명시하세요.

요금 및 크레딧

비디오 생성 시 요금은 초 단위의 과금 대상 시간을 기준으로 크레딧으로 차감됩니다. 비디오 입력이 없는 경우 과금 대상 시간은 출력된 비디오의 재생 시간이 되며, 비디오 입력이 있는 경우에는 참조 비디오의 재생 시간도 포함됩니다.

아래 표는 작업의 총비용이 아닌 초당 차감되는 크레딧을 나타냅니다. 요금은 모델, 출력 해상도 및 비디오 투 비디오(Reference-to-Video) 모드에서 참조 비디오 제공 여부에 따라 달라집니다. 총비용 계산 방법은 표 아래의 공식과 예시를 참고해 주세요.

출력 해상도참조 비디오 없음참조 비디오 있음
480p초당 7 크레딧초당 5 크레딧
720p초당 10 크레딧초당 7 크레딧
  • 참조 비디오가 없는 경우: 생성된 비디오의 재생 시간(초) × 참조 비디오 없음 요율
  • 참조 비디오가 있는 경우: (생성된 비디오의 재생 시간(초) + 검증된 참조 비디오의 재생 시간(초)) × 참조 비디오 있음 요율. 서버에서 참조 비디오의 총 재생 시간을 확인한 후, 정수(초 단위)로 올림 처리하여 요금을 산정합니다.
  • 이미지나 오디오 레퍼런스만 사용하는 경우에는 '참조 비디오 없음' 요율이 적용됩니다. '참조 비디오 있음' 요율은 오직 레퍼런스 비디오 모드에서 참조 비디오를 직접 전달한 경우에만 적용됩니다.

요금 계산 예시

5초 분량의 720p 텍스트로 비디오 생성: 5 × 10 = 50 크레딧.

5초 분량의 720p 비디오 출력 및 5초 분량의 참조 비디오 사용: (5 + 5) × 7 = 70 크레딧.

이 크레딧은 작업 생성 시 선차감됩니다. 작업이 성공하면 이 금액이 최종 요금으로 확정되며, 실제 출력 길이에 따라 추가로 차감되거나 부분 환불되지 않습니다. 작업이 실패하거나 시간 초과된 경우에는 환불 절차가 진행됩니다.

크레딧은 작업이 접수될 때 가예약 상태가 되며, 작업이 정상적으로 완료되면 실제 차감됩니다. 실패하거나 제한 시간을 초과한 작업은 자동으로 환불 절차를 밟게 됩니다. 만약 정산 상태가 refund_failed로 표시된다면 환불이 정상적으로 완료되지 않은 것이므로, API 로그를 확인하시거나 고객 지원팀에 문의해 주세요.

duration=-1일 때 크레딧 차감 방식

duration을 -1로 설정하면 최종 출력 길이는 고정되지 않으며, 모델이 자체적으로 판단하여 결정합니다.

대부분의 경우 duration은 -1 대신 실제 필요한 비디오 길이로 설정하는 것이 좋습니다. -1 설정은 다른 비디오 생성 시나리오가 아닌, 비디오 편집 기능에만 사용하시는 것을 권장합니다.

참조 입력값차감액 계산 방식예시
참조 동영상이 있는 경우모든 참조 동영상의 길이를 합산한 후 소수점 첫째 자리에서 올림하여 초 단위(T)로 계산합니다. 차감액은 (T + T) × 동영상 포함 요율로 계산되며, 앞의 T는 예상 출력 길이, 뒤의 T는 입력 동영상 길이를 의미합니다.720p, 5초 참조 동영상 포함: (5 + 5) × 7 = 70 크레딧
참조 동영상이 없는 경우 (이미지 또는 오디오만 있는 경우)예상 출력 길이를 30초로 고정하여 계산합니다. 차감액은 30 × 동영상 미포함 요율입니다.720p, 참조 동영상 없음: 30 × 10 = 300 크레딧

인증

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

기본 URL

https://api.seevio.ai
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

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

빠른 시작

최소한의 파라미터로 아래 요청을 전송하고, 반환된 taskId를 저장한 후 작업 조회 예시를 통해 진행 상황을 확인하세요. 작업 생성 응답에 포함된 credits 값은 가예약된 크레딧 금액을 나타냅니다.

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-flash",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

작업 생성 응답 예시

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

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

작업 생성

POST https://api.seevio.ai/v1/videos/generations

model과 input이 포함된 JSON 객체를 전송하며, callback_url은 선택 사항입니다. 모델 ID는 항상 이 페이지에 표시된 대로 지정해야 합니다. 모델 ID를 생략하면 seedance-2-0이 기본으로 선택됩니다.

요청 본문

필드타입필수 여부설명 및 제약 조건
model
string예

모델 ID. Seedance 2.5 Flash을(를) 사용하려면 이 필드를 seedance-2-5-flash(으)로 설정하세요.

callback_url
string아니요

작업이 성공하거나 실패했을 때 POST 콜백을 수신할 수 있는 공개 HTTPS 엔드포인트 주소입니다. 사설망 주소나 localhost는 지원하지 않습니다.

예시: https://example.com/webhooks/seevio
input
object예

생성에 필요한 설정값입니다. 비어 있지 않은 유효한 prompt 값이 포함되어야 합니다.

입력 파라미터

image-to-video 모드에서는 image_urls 입력이 필수입니다. reference-to-video 모드에서는 image_urls, video_urls, audio_urls 중 하나 이상을 필수로 지정해야 합니다.

image_urls, video_urls, audio_urls는 URL 문자열 배열(string[]) 형태로 제공해야 합니다. 제공되는 모든 URL은 HTTPS를 통해 공개적으로 접근할 수 있어야 하며, 이는 선택한 모드에서 처리되지 않고 제외되는 미디어 파일에도 동일하게 적용됩니다.

필드타입필수 여부기본값설명 및 제약 조건
input.prompt
string예—

모든 모드에서 프롬프트 입력은 필수입니다. 공백을 제외하고 최대 10,000자까지 입력할 수 있으며, 공백으로만 구성할 수는 없습니다.

예시: A cat surfing at sunset
input.generation_type
string아니요text-to-video
지원하는 값
text-to-video | image-to-video | reference-to-video

text-to-video, image-to-video 또는 reference-to-video를 선택합니다. 생략하면 text-to-video가 기본값이며 프롬프트만 사용합니다. image-to-video는 순서대로 지정한 1~2장의 프레임 이미지를 사용합니다. reference-to-video는 이미지, 동영상, 오디오를 참고하며, 오디오만 제공할 수도 있습니다. 프롬프트는 항상 필수입니다.

input.image_urls
string[]조건부 필수[]

생성할 영상의 외형을 참고할 이미지 URL을 제공합니다. image-to-video에서는 첫 프레임 이미지 1장 또는 첫 프레임과 마지막 프레임 순서로 2장을 제공합니다. reference-to-video에서는 최대 30장까지 사용할 수 있습니다. 각 이미지는 30 MB 미만이어야 하며 형식과 크기 조건은 아래 미디어 요구사항을 참고하세요. 모든 종류의 참고 자료를 합쳐 최대 50개 파일까지 허용됩니다. 생략하면 []이며 text-to-video에서는 무시됩니다.

예시: ["https://example.com/first-frame.jpg"]
input.video_urls
string[]조건부 필수[]

움직임을 참고하거나 영상을 편집·연장하기 위한 동영상 URL을 제공합니다. reference-to-video에서만 사용합니다. 최대 10개 파일을 사용할 수 있으며 각 파일은 100 MB 이하, 길이는 2~30초여야 합니다. 동영상의 총길이는 30초 이하여야 합니다. 모든 종류의 참고 자료를 합쳐 최대 50개 파일까지 허용됩니다. 서버가 동영상 길이를 측정해 요금을 계산합니다. 생략하면 []이며 다른 모드에서는 무시됩니다.

예시: ["https://example.com/source.mp4"]
input.audio_urls
string[]조건부 필수[]

소리를 참고할 오디오 URL을 제공합니다. reference-to-video에서만 사용합니다. 최대 10개의 MP3/WAV 파일을 사용할 수 있으며 각 파일은 15 MB 이하, 길이는 2~30초여야 합니다. 오디오의 총길이는 30초 이하여야 합니다. 모든 종류의 참고 자료를 합쳐 최대 50개 파일까지 허용됩니다. 오디오만 참고 자료로 제공할 수도 있지만 프롬프트는 필수입니다. 생략하면 []이며 다른 모드에서는 무시됩니다.

예시: ["https://example.com/music.mp3"]
input.duration
integer아니요5
지원하는 값
-1 | 4–30

4초에서 30초 사이의 정수 값으로 출력 비디오 길이를 설정합니다. reference-to-video 모드에 한하여 -1 설정이 허용됩니다. 소스 비디오 편집 워크플로우 시 유용하며, 요금 부과는 앞서 설명한 특수 규칙을 따릅니다.

예시: 5
input.aspect_ratio
string아니요adaptive
지원하는 값
16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive

16:9, 4:3, 1:1, 3:4, 9:16, 21:9 또는 adaptive를 선택합니다. 생략하면 adaptive가 기본값이며 모델이 출력 화면 비율을 결정합니다. 영상 편집이나 연장 시에는 adaptive를 사용하세요. image-to-video 모드에서는 adaptive 화면 비율만 지원하므로 이 필드를 생략하거나 adaptive로 명시하세요.

예시: adaptive
input.resolution
string아니요720p
지원하는 값
480p | 720p

480p 또는 720p를 선택합니다. 생략하면 지원되는 모든 생성 모드에서 720p가 기본값입니다. 더 높은 해상도를 지정하면 요청이 거부됩니다.

예시: 720p
input.generate_audio
boolean아니요true
지원하는 값
true | false

true는 동기화된 오디오 생성을 요청하고 false는 오디오 생성을 비활성화합니다. 생략하면 기본값은 true입니다. 지원되는 모든 생성 모드에 적용됩니다.

예시: true
input.watermark
boolean아니요false
지원하는 값
true | false

true는 출력 영상에 AI 워터마크를 추가하도록 요청하고 false는 해당 워터마크 없이 출력하도록 요청합니다. 생략하면 기본값은 false입니다. 지원되는 모든 생성 모드에 적용됩니다.

예시: false
input.web_search
boolean아니요false
지원하는 값
true | false

true는 모델에서 이용 가능한 경우 웹 검색을 허용하고 false는 비활성화합니다. 생략하면 기본값은 false입니다. 활성화해도 실제 검색이 수행된다고 보장되지는 않습니다.

예시: false
input.return_last_frame
boolean아니요false
지원하는 값
true | false

true는 생성된 영상의 마지막 프레임을 요청하고 false는 요청하지 않습니다. 생략하면 기본값은 false입니다. 지원되는 모든 생성 모드에 적용됩니다. 요청한 프레임이 제공되면 URL이 data.last_frame_url에 반환되며, 그렇지 않으면 null입니다.

예시: true
input.seed
integer아니요—
지원하는 값
-1부터 2147483647까지

-1부터 2147483647 사이의 정수 값입니다. -1로 설정 시 임의의 무작위 시드가 부여됩니다.

예시: 42
input.output_format
string아니요mp4
지원하는 값
mp4 | mov

mp4 또는 mov를 선택합니다. 생략하면 mp4가 기본값입니다. 지원되는 모든 생성 모드에서 출력 컨테이너 형식을 지정합니다.

참/거짓(Boolean) 필드는 문자열이나 숫자가 아닌 JSON true 혹은 false여야 합니다.

생성 응답

HTTP 200 응답은 taskId(문자열)와 credits(숫자)를 반환합니다. 이는 작업의 성공적인 완료가 아닌, 접수가 완료되었음을 나타냅니다. 아래의 예시 값은 5초 720p 빠른 시작 요청의 가예약 금액을 기준으로 산정되었습니다.

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

생성 모드 및 예시

코드 내의 example.com 미디어 URL 주소는 사용자가 직접 접근 가능한 HTTPS 파일 주소로 대체하여 테스트해 주세요. 예시 URL은 API 요청 양식을 보여주기 위한 용도이며 실제로 다운로드 가능한 파일이 아닙니다.

텍스트로 비디오 생성

텍스트 프롬프트를 사용하여 비디오를 생성합니다. 이 모드에서는 미디어 URL을 입력하더라도 전달되지 않습니다.

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-flash",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

첫 프레임 지정

첫 프레임으로 사용할 이미지 1개를 제공하고, 프롬프트를 통해 만들고자 하는 비디오의 움직임을 묘사합니다.

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-flash",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "aspect_ratio": "adaptive"
  }
}'

첫 프레임 및 마지막 프레임 지정

첫 프레임과 마지막 프레임 순으로 정렬된 2개의 이미지 URL을 제공합니다. 이 예시는 생성된 비디오의 마지막 프레임 컷도 별도로 함께 요청합니다.

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-flash",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "aspect_ratio": "adaptive",
    "return_last_frame": true
  }
}'

멀티모달 레퍼런스

이미지, 비디오, 오디오 레퍼런스를 복합적으로 조합하여 생성합니다. 프롬프트는 필수로 작성해야 하며, 참조 비디오가 입력되는 경우 요금 정책이 달라집니다.

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-flash",
  "input": {
    "prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "reference-to-video",
    "image_urls": [
      "https://example.com/character.jpg"
    ],
    "video_urls": [
      "https://example.com/camera.mp4"
    ],
    "audio_urls": [
      "https://example.com/ambience.mp3"
    ],
    "aspect_ratio": "adaptive"
  }
}'

오디오 레퍼런스

오디오만을 참조 유형으로 입력하고, 필수 텍스트 프롬프트를 작성하여 생성할 비디오의 연출 방향을 묘사합니다.

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-flash",
  "input": {
    "prompt": "Create a coastal sunrise scene matching the rhythm of this audio.",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "reference-to-video",
    "audio_urls": [
      "https://example.com/music.mp3"
    ]
  }
}'

비디오 편집

Seedance 2.5 Flash 비디오 편집을 사용하려면 duration을 -1로, aspect_ratio를 adaptive로 설정해야 합니다. 두 가지 모두 필수 설정이며, 그렇지 않으면 생성에 실패합니다.

편집 요청 내용을 명시하고 원본 비디오를 전달합니다. duration을 -1로 설정하고 화면 비율은 adaptive로 지정하세요. 이 가이드를 따르기 위해 원본 영상은 최소 4초 이상이어야 합니다. duration=-1 설정 시 요금 정산 방식은 위에 설명된 안내를 따릅니다.

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-flash",
  "input": {
    "prompt": "Edit the source video: change the character’s coat to blue and preserve the camera movement.",
    "duration": -1,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "reference-to-video",
    "video_urls": [
      "https://example.com/source.mp4"
    ],
    "aspect_ratio": "adaptive"
  }
}'

비디오 확장

Seedance 2.5 Flash 비디오 확장 기능을 사용할 때는 aspect_ratio를 adaptive로 설정해야 생성 실패를 방지할 수 있습니다. 길이는 -1을 사용할 필요 없이 지원되는 범위 내에서 원하는 출력 비디오 길이에 맞춰 정상적으로 설정해 주세요.

원본 비디오 이후에 이어질 내용을 프롬프트에 묘사합니다. 화면 비율을 adaptive로 설정하고, 모델이 지원하는 일반적인 범위 내의 출력 재생 시간을 설정하세요.

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-flash",
  "input": {
    "prompt": "Continue the camera movement from the source video, revealing a forest clearing.",
    "duration": 8,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "reference-to-video",
    "video_urls": [
      "https://example.com/source.mp4"
    ],
    "aspect_ratio": "adaptive"
  }
}'

작업 조회

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

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

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5-flash",
  "is_draft": false,
  "draft_task_id": null,
  "status": "completed",
  "billing_status": "charged",
  "credits": 50,
  "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-flash",
  "is_draft": false,
  "draft_task_id": null,
  "status": "failed",
  "billing_status": "refunded",
  "credits": 50,
  "failed_reason": "provider_failed"
}

웹훅

작업 생성 시 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-flash",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "seed": 42,
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

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

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

created_at은 이벤트 생성 시간이고 task_created_at은 작업 생성 시간이며 모두 Unix 초 단위입니다. 예시는 권장 필드를 보여 주며 실제 응답에는 추가 필드가 포함될 수 있습니다.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "seedance-2-5-flash",
  "status": "completed",
  "task_created_at": 1788652800,
  "billing_status": "charged",
  "credits": 50,
  "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가 포함됩니다. id로 작업을 식별하고, failed_reason에서 실패 원인을, credits_refunded에서 환불된 크레딧 수량을 확인하세요.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "seedance-2-5-flash",
  "status": "failed",
  "task_created_at": 1788652800,
  "billing_status": "refunded",
  "credits": 50,
  "failed_reason": "provider_failed",
  "credits_refunded": 50
}

수신 서버 구현 예시

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;
    // 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)에 대기시키는 것이 좋습니다.

미디어 요구 사양 및 제한 사항

  • 모든 미디어 자원 및 콜백 URL은 외부에서 접근할 수 있는 공개 HTTPS 주소여야 합니다. 로컬호스트 주소, 사설 IP 대역, 혹은 쿠키나 별도의 세션 로그인이 필요한 주소는 사용이 불가합니다. 참조 비디오 및 오디오 URL은 즉시 읽기가 가능한 미디어 파일 경로로 연결되어야 합니다.
  • reference-to-video 모드를 사용할 때는 최소 하나 이상의 참조 파일이 요구되며, 이미지 30개, 비디오 10개, 오디오 10개, 총 미디어 소재 50개 이하의 한도를 준수해야 합니다. 입력하는 비디오의 총 연장 길이와 오디오의 총 연장 길이는 각각 최대 30초 이하여야 합니다.
  • text-to-video 모드에서는 사용자가 입력한 모든 미디어 참조 필드를 무시합니다. image-to-video 모드는 전달받은 이미지 리스트 중 첫 프레임과 마지막 프레임용 이미지 정보만 파싱하며, 비디오나 오디오 관련 설정은 무시합니다. 다양한 미디어를 혼합하여 연출하려면 reference-to-video 모드를 활성화하세요.
  • 개별 참조 비디오 및 오디오 파일의 재생 시간은 최소 2초에서 최대 30초 사이여야 합니다. 비디오 편집 가이드 예시를 수행하시려면 최소 4초 이상의 소스 클립을 준비해 주세요.

이미지 권장 사항

  • 각 이미지 용량은 30MB 미만이어야 합니다.
  • 지원 형식: jpeg, png, webp, bmp, tiff, gif
  • 가로세로 비율(너비 ÷ 높이): 0.4 이상 2.5 이하
  • 가로 및 세로 해상도는 각각 300~6,000픽셀 사이여야 합니다.

동영상 권장 사항

  • 지원 형식: mp4, mov
  • 각 동영상 용량은 100MB를 초과할 수 없습니다.
  • 프레임 레이트: 24~60 FPS
  • 가로세로 비율(너비 ÷ 높이): 0.4 이상 2.5 이하
  • 총 픽셀 수(너비 × 높이): 407,696픽셀 이상 8,295,044픽셀 이하여야 합니다. (예: 614 × 664 = 407,696 및 3,326 × 2,494 = 8,295,044) 이는 총 픽셀 수의 예시이며, 고정된 가로세로 해상도 요구 사항이 아닙니다.

오디오 권장 사항

  • 지원 형식: wav, mp3
  • 각 오디오 파일 용량은 15MB를 초과할 수 없습니다.