Video Generations
영상 생성을 요청하고 진행 상태를 조회할 작업 ID를 받으세요.
Seedance 요청을 비동기로 처리하므로 HTTP 200은 생성 완료가 아닌 요청 접수를 뜻합니다.
https://gw.letsur.ai/v1/video/generationsAuthorization: Bearer <API_KEY>지원 범위와 인증
이 페이지는 Seedance 모델 byteplus-seedance-2.5의 요청을 설명합니다. 현재 스페이스에서 이 모델을 사용할 수 있는지와 적용 단가는 에셋에서 확인합니다. 모델이 보이지 않거나 이용 조건을 확인해야 한다면 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다.
요청 URL은 https://gw.letsur.ai/v1/video/generations입니다. AI 게이트웨이 API 키를 Bearer 헤더로 보냅니다. OpenAI 호환 API와 같은 인증 헤더를 쓰지만, 이 요청은 아래의 별도 JSON 계약을 따릅니다. 공통 설정은 인증과 요청 헤더를 확인합니다.
요청 필드
본문은 application/json입니다. 아래에 없는 필드나 공급사 전용 필드 이름을 보내지 않습니다.
| 필드 | 타입 | 조건과 기본값 |
|---|---|---|
model | string | 필수. byteplus-seedance-2.5 |
prompt | string | 필수. 비어 있지 않은 영상 설명 |
image_url | string | 선택. 첫 프레임 이미지. 프레임 조합은 다음 절 참고 |
references | array | 선택. 이미지, 영상 또는 오디오 참조 |
mode | string | 영상 참조가 있을 때만 reference, edit, extend 사용 |
duration | integer | 4–30초 또는 자동 선택 -1. 일반 생성 기본 5초, edit와 extend 기본 -1 |
resolution | string | 480p(기본), 720p, 1080p |
aspect_ratio | string | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive. 기본값과 제한은 입력 방식에 따라 다름 |
generate_audio | boolean | 오디오 생성 여부. 기본 true |
seed | integer | 선택. 공급사에 전달할 시드. 같은 결과의 재현을 보장하지 않음 |
watermark | boolean | 선택. 워터마크 옵션 |
return_last_frame | boolean | 선택. 마지막 프레임 반환 옵션 |
store_media | boolean | 선택. 생략하면 스페이스 설정, false는 임시 보관, true는 결과 보관. 보관 조건 참고 |
선택값을 생략하면 기본값을 사용합니다. 명시한 값의 타입이나 범위가 잘못되면 요청이 거절됩니다. 해상도와 생성 길이는 사용량에 영향을 주며, 영상 참조 유무에 따라 적용 단가가 달라질 수 있습니다.
입력 조합
references의 각 원소는 다음 객체입니다. 문자열로 파일 ID만 보내지 않습니다.
| 원소 필드 | 타입 | 필수 여부와 값 |
|---|---|---|
type | string | 필수. image, video, audio |
url | string | 필수. 해당 입력에서 지원되는 HTTPS URL 또는 업로드 응답의 파일 참조 |
role | string | 선택. 이미지에 first_frame, last_frame, reference_image; 영상에 reference_video; 오디오에 reference_audio. 생략 시 해당 종류의 일반 참조 역할 |
첫 프레임, 마지막 프레임, 일반 참조와 영상 편집 또는 연장의 조합은 Seedance 2.5 입력 방식을 따릅니다. 참조 파일은 References의 반환 참조를 해당 URL 필드에 넣습니다.
최소 요청과 접수 응답
최소 요청 본문은 다음과 같습니다. 실행 환경과 안전한 키 입력부터 이어지는 예제는 영상 생성하고 파일 받기에서 확인합니다.
{
"model": "byteplus-seedance-2.5",
"prompt": "바람에 천천히 흔들리는 초원의 풀을 고정 카메라로 촬영한 영상"
}접수에 성공하면 HTTP 200과 작업 ID를 반환합니다. 아래 ID는 설명용입니다.
{"id": "lst-example-job-id"}id를 저장한 뒤 작업 조회에 사용합니다. HTTP 200은 요청 접수이며 영상 생성, 파일 준비 또는 비용 확정을 뜻하지 않습니다.
거절과 응답 유실
입력 오류는 응답의 상세 내용을 확인해 필드와 조합을 수정합니다. 대기열 한도로 거절되면 Retry-After가 있을 때 해당 값을 따릅니다. 인증 및 공통 오류는 오류 처리를 확인합니다.
접수 응답을 받지 못했다면 요청이 접수되지 않았다고 단정할 수 없습니다. 생성 POST를 자동으로 반복하면 별도 작업이 만들어질 수 있습니다. 이미 ID를 받았다면 새 요청 대신 같은 작업을 조회합니다.
작업 ID도 받지 못했다면 다시 생성하지 말고 요청 시각, 스페이스와 모델 코드를 기록하세요. 접수 여부를 확인할 수 없을 때의 문의 방법으로 원래 요청의 처리 여부를 확인합니다.