Seedance 2.0 Mini
텍스트, 첫/마지막 프레임 이미지, 멀티모달 레퍼런스를 사용하여 Seedance 2.0 Mini(으)로 비디오를 생성합니다. 이 페이지에서는 이 모델의 전체 요청-응답 워크플로우를 다룹니다.
API 모델 ID: seedance-2-0-mini
비디오 생성은 비동기 방식으로 처리됩니다. 작업을 생성할 때 반환되는 taskId를 저장한 후, 해당 ID로 진행 상태를 조회하거나 웹훅으로 결과를 수신하세요.
지원 기능
| 기능 | 지원하는 값 |
|---|---|
| 출력 해상도 | 480p · 720p |
| 출력 재생 시간 | 4~15초 |
| 화면 비율 | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive |
| 참조 이미지 | 이미지 최대 9장 |
| 참조 비디오 | 동영상 최대 3개 |
| 참조 오디오 파일 | 오디오 파일 최대 3개 |
| 전체 참조 미디어 합계 | 참조 파일 총 12개까지 |
| 비디오/오디오 그룹별 총 재생 시간 | 15초 |
| seed | -1부터 4294967295까지 |
요금 및 크레딧
비디오 생성 시 요금은 초 단위의 과금 대상 시간을 기준으로 크레딧으로 차감됩니다. 비디오 입력이 없는 경우 과금 대상 시간은 출력된 비디오의 재생 시간이 되며, 비디오 입력이 있는 경우에는 참조 비디오의 재생 시간도 포함됩니다.
아래 표는 작업의 총비용이 아닌 초당 차감되는 크레딧을 나타냅니다. 요금은 모델, 출력 해상도 및 비디오 투 비디오(Reference-to-Video) 모드에서 참조 비디오 제공 여부에 따라 달라집니다. 총비용 계산 방법은 표 아래의 공식과 예시를 참고해 주세요.
| 출력 해상도 | 참조 비디오 없음 | 참조 비디오 있음 |
|---|---|---|
480p | 초당 3 크레딧 | 초당 2 크레딧 |
720p | 초당 6 크레딧 | 초당 4 크레딧 |
- 참조 비디오가 없는 경우: 생성된 비디오의 재생 시간(초) × 참조 비디오 없음 요율
- 참조 비디오가 있는 경우: (생성된 비디오의 재생 시간(초) + 검증된 참조 비디오의 재생 시간(초)) × 참조 비디오 있음 요율. 서버에서 참조 비디오의 총 재생 시간을 확인한 후, 정수(초 단위)로 올림 처리하여 요금을 산정합니다.
- 이미지나 오디오 레퍼런스만 사용하는 경우에는 '참조 비디오 없음' 요율이 적용됩니다. '참조 비디오 있음' 요율은 오직 레퍼런스 비디오 모드에서 참조 비디오를 직접 전달한 경우에만 적용됩니다.
요금 계산 예시
5초 분량의 720p 텍스트로 비디오 생성: 5 × 6 = 30 크레딧.
5초 분량의 720p 비디오 출력 및 5초 분량의 참조 비디오 사용: (5 + 5) × 4 = 40 크레딧.
크레딧은 작업이 접수될 때 가예약 상태가 되며, 작업이 정상적으로 완료되면 실제 차감됩니다. 실패하거나 제한 시간을 초과한 작업은 자동으로 환불 절차를 밟게 됩니다. 만약 정산 상태가 refund_failed로 표시된다면 환불이 정상적으로 완료되지 않은 것이므로, API 로그를 확인하시거나 고객 지원팀에 문의해 주세요.
인증
API 대시보드에서 API 키를 생성하세요. 생성된 전체 API 키 값은 최초 1회만 노출됩니다. 키를 서버 측에 안전하게 보관하고, 모든 API 요청 시 Bearer 토큰으로 포함하여 전송해 주세요.
기본 URL
https://api.seevio.aiAuthorization: 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-0-mini",
"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": 30
}작업 생성
POST https://api.seevio.ai/v1/videos/generations모델 ID, 입력 데이터 및 선택 옵션인 callback_url을 포함한 JSON 객체를 전송하세요. 항상 이 페이지에 표시된 정확한 모델 ID를 명시해야 합니다. model 파라미터를 생략하면 기본값인 seedance-2-0 모델이 선택됩니다.
요청 본문
| 필드 | 타입 | 필수 여부 | 설명 및 제약 조건 |
|---|---|---|---|
model | string | 예 | 모델 ID. Seedance 2.0 Mini을(를) 사용하려면 이 필드를 seedance-2-0-mini(으)로 설정하세요. |
callback_url | string | 아니요 | 작업이 성공하거나 실패했을 때 POST 콜백을 수신할 수 있는 공개 HTTPS 엔드포인트 주소입니다. 사설망 주소나 localhost는 지원하지 않습니다. 예시: https://example.com/webhooks/seevio |
input | object | 예 | 생성에 필요한 설정값입니다. 비어 있지 않은 유효한 prompt 값이 포함되어야 합니다. |
입력 파라미터
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 모드는 1~2개의 이미지를 사용합니다. reference-to-video 모드는 이미지, 비디오, 오디오 레퍼런스를 함께 사용할 수 있습니다. 지원하는 값 text-to-video | image-to-video | reference-to-video |
input.image_urls | string[] | 조건부 필수 | [] | image-to-video 모드: 첫 프레임용 이미지 1개 또는 첫 프레임과 마지막 프레임용 순서대로 정렬된 이미지 2개를 전달합니다. reference-to-video 모드: 최대 9개의 이미지를 전달할 수 있습니다. text-to-video 모드에서는 무시됩니다. 예시: ["https://example.com/first-frame.jpg"] |
input.video_urls | string[] | 조건부 필수 | [] | reference-to-video 모드에서만 전달할 수 있습니다. 총합 최대 3개의 비디오 및 총 15초 이내의 미디어를 전달할 수 있습니다. 다른 모드에서는 무시됩니다. 예시: ["https://example.com/source.mp4"] |
input.audio_urls | string[] | 조건부 필수 | [] | reference-to-video 모드에서만 전달할 수 있습니다. 총합 최대 3개의 오디오 파일 및 총 15초 이내의 미디어를 전달할 수 있습니다. 다른 모드에서는 무시됩니다. 이 모델에서는 오디오만 단독으로 참조 자료로 사용할 수 없습니다. audio_urls를 제공할 때는 image_urls에 하나 이상의 참조 이미지 또는 video_urls에 하나 이상의 참조 비디오를 함께 제공해야 합니다. 예시: ["https://example.com/music.mp3"] |
input.duration | integer | 아니요 | 5 | 4초에서 15초 사이의 정수 값으로 출력 비디오 길이를 설정합니다. 지원하는 값 4–15예시: 5 |
input.aspect_ratio | string | 아니요 | adaptive | 출력 비디오의 화면 비율입니다. adaptive로 설정 시 모델이 자체적으로 가장 적절한 화면 비율을 결정합니다. 지원하는 값 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive예시: adaptive |
input.resolution | string | 아니요 | 720p | 여기에 제공되는 지원 해상도 목록 중 하나를 선택해 주세요. 지원하는 값 480p | 720p예시: 720p |
input.generate_audio | boolean | 아니요 | true | 비디오와 동기화된 오디오 생성 여부를 선택합니다. 지원하는 값 true | false예시: true |
input.watermark | boolean | 아니요 | false | 생성된 비디오에 AI 워터마크를 삽입할지 여부를 선택합니다. 지원하는 값 true | false예시: false |
input.web_search | boolean | 아니요 | false | 모델이 지원하는 경우, 웹 검색 결과를 활용한 생성을 허용합니다. 지원하는 값 true | false예시: false |
input.return_last_frame | boolean | 아니요 | false | 마지막 프레임의 이미지를 함께 요청합니다. 생성이 완료되면 조회 결과의 data.last_frame_url 필드에 값으로 제공되며, 사용 불가능한 상태라면 null이 반환됩니다. 지원하는 값 true | false예시: true |
input.seed | integer | 아니요 | -1 | -1부터 4294967295 사이의 정수 값입니다. -1로 설정 시 임의의 무작위 시드가 부여됩니다. 지원하는 값 -1부터 4294967295까지예시: 42 |
참/거짓(Boolean) 필드는 문자열이나 숫자가 아닌 JSON true 혹은 false여야 합니다.
생성 응답
HTTP 200 응답은 taskId(문자열)와 credits(숫자)를 반환합니다. 이는 작업의 성공적인 완료가 아닌, 접수가 완료되었음을 나타냅니다. 아래의 예시 값은 5초 720p 빠른 시작 요청의 가예약 금액을 기준으로 산정되었습니다.
{
"taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
"credits": 30
}생성 모드 및 예시
텍스트로 비디오 생성
텍스트 프롬프트를 사용하여 비디오를 생성합니다. 이 모드에서는 미디어 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-0-mini",
"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
}
}'첫 프레임 지정
첫 프레임으로 사용할 이미지 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-0-mini",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"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-0-mini",
"input": {
"prompt": "A cat surfing at sunset, cinematic lighting",
"duration": 5,
"resolution": "720p",
"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-0-mini",
"input": {
"prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
"duration": 5,
"resolution": "720p",
"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"
}
}'작업 조회
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-0-mini",
"status": "completed",
"billing_status": "charged",
"credits": 30,
"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-0-mini",
"status": "failed",
"billing_status": "refunded",
"credits": 30,
"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-0-mini",
"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-0-mini",
"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-0-mini",
"status": "failed",
"data": {
"failed_reason": "provider_failed",
"credits_refunded": 30
}
}수신 서버 구현 예시
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)에 대기시키는 것이 좋습니다.
미디어 요구 사양 및 제한 사항
- 모든 미디어 자원 및 콜백 URL은 외부에서 접근할 수 있는 공개 HTTPS 주소여야 합니다. 로컬호스트 주소, 사설 IP 대역, 혹은 쿠키나 별도의 세션 로그인이 필요한 주소는 사용이 불가합니다. 참조 비디오 및 오디오 URL은 즉시 읽기가 가능한 미디어 파일 경로로 연결되어야 합니다.
- reference-to-video 모드를 사용할 때는 최소 하나 이상의 참조 파일이 요구되며, 이미지 9개, 비디오 3개, 오디오 3개, 총 미디어 소재 12개 이하의 한도를 준수해야 합니다. 입력하는 비디오의 총 연장 길이와 오디오의 총 연장 길이는 각각 최대 15초 이하여야 합니다.
- text-to-video 모드에서는 사용자가 입력한 모든 미디어 참조 필드를 무시합니다. image-to-video 모드는 전달받은 이미지 리스트 중 첫 프레임과 마지막 프레임용 이미지 정보만 파싱하며, 비디오나 오디오 관련 설정은 무시합니다. 다양한 미디어를 혼합하여 연출하려면 reference-to-video 모드를 활성화하세요.
- Seedance 2.0 모델군을 사용할 때는 모델 호환성을 위해 오디오 파일 입력 시 최소 하나 이상의 이미지 또는 비디오를 함께 제공해야 합니다. 오디오만 단독으로 참조하는 예제 구성은 Seedance 2.5 문서 페이지에서 제공하고 있습니다.
- Fast 및 Mini 서비스 티어는 480p와 720p 해상도를 지원합니다. 요청 검증 시 높은 해상도의 문자열을 입력하더라도 실제 사용 중인 모델의 스펙에 해당되지 않으면 지원 대상이 아니므로 거부될 수 있습니다.
이미지 권장 사항
- 각 이미지 용량은 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를 초과할 수 없습니다.
오류 처리
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 세부 로그를 자세히 살펴보세요. 동일 요청 재시도 시 불필요하게 가예약 및 청구 처리가 중복 발생할 위험이 있으므로 재시도 시 주의해 주십시오. |
호출 비율 제한
태스크 생성: API 키당 기본적으로 분당 최대 100회의 요청이 허용됩니다. 현재 맞춤형 속도 제한은 제공되지 않습니다.
태스크 조회: API 키당 기본적으로 분당 최대 120회의 요청이 허용됩니다. 조회 요청과 태스크 생성 요청은 각각 별도로 계산됩니다.