Video Generations
영상 생성 요청과 비동기 작업 접수
모든 모델에 공통인 필드와 이름을 맞춘 필드, 접수 응답의 작업 ID, 결과 보관 설정을 설명하고, 요청이 거절되거나 응답을 받지 못했을 때 확인할 사항을 안내합니다.
페이지 목차
https://gw.letsur.ai/v1/video/generationsAuthorization: Bearer <API_KEY>지원 범위와 인증
이 엔드포인트로 영상 생성 요청을 보내면 응답으로 작업 ID를 받습니다. 이 ID로 작업을 조회하고 결과 파일의 다운로드 링크를 발급받는 방법은 모델과 관계없이 같습니다. 요청 본문에 쓸 수 있는 필드와 입력 조건은 모델마다 다릅니다. 요청을 보내고 결과 파일을 받기까지의 전체 과정은 생성 요청하고 결과 파일 받기에 있습니다.
현재 스페이스의 모델 사용 가능 여부와 적용 단가는 에셋에서 확인합니다. 에셋에 모델이 보이지 않거나 이용 조건을 확인해야 한다면 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다.
요청 URL은 https://gw.letsur.ai/v1/video/generations입니다. AI 게이트웨이 API 키를 Bearer 헤더로 보냅니다. 인증 헤더는 OpenAI 호환 API와 같지만, 요청 본문의 JSON 형식은 모델마다 다릅니다. 공통 설정은 인증과 요청 헤더에 있습니다.
지원 모델
아래 표의 모든 모델이 렛서 필드 이름을 사용합니다. 모델 코드와 받는 필드, 허용 값은 각 모델 가이드에서 확인합니다. 셋째 열부터는 모델마다 지원이 다른 기능입니다.
| 모델 | 받는 필드와 입력 조합 | 관리형 참조 letsur-asset://… | 마지막 프레임 반환 | 접수 응답의 Response.TaskId |
|---|---|---|---|---|
| Seedance 2.5 | 요청 필드, 입력 방식 | 받음 | 지원 | 없음 |
| Seedance 2.0 계열 | 요청 필드, 참조 조건 | 받음 | 지원 | 없음 |
| Kling | 요청 필드와 허용 값, 참조 입력 | 받지 않음 | 지원하지 않음 | 있음 |
요청 필드
요청 본문은 application/json으로 보냅니다. 모든 모델에 공통인 필드는 model과 store_media 두 개입니다.
기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.
| 필드 | 타입 | 요구 여부 | 기본값 | 설명 |
|---|---|---|---|---|
model | string | 필수 | - | 호출할 모델 코드. 지원 모델에 연결한 모델 가이드 참고 |
store_media | boolean | 선택 | 스페이스 설정 | true 또는 false. false는 임시 보관, true는 결과 보관. 결과 보관 선택하기 참고 |
그 밖의 지원 필드, 허용 값과 기본값, 입력 조합은 모델마다 다릅니다. 사용할 모델의 필드는 지원 모델 표에 연결한 모델 가이드에서 확인합니다. 한 모델용으로 작성한 본문을 다른 모델에 그대로 보내지 마세요. 사용할 모델의 가이드에 없는 필드는 보내지 않습니다. 명시한 값의 타입이나 범위가 잘못되면 요청이 거절됩니다.
로컬 파일을 입력하려면 References로 업로드한 뒤 반환된 참조를 모델 가이드가 안내하는 필드에 지정합니다.
렛서 필드 이름
지원 모델 표의 모델은 다음 필드를 같은 이름으로 사용합니다.
prompt,image_urlreferences와 그 원소의type,url,rolemode,duration,resolution,aspect_ratio,generate_audio,watermark
필드별 지원 여부, 허용 값과 기본값은 각 모델 가이드에서 확인합니다. 이 목록에 없는 필드는 모델마다 이름이 다를 수 있습니다.
최소 요청과 접수 응답
요청 본문의 형식은 모델마다 다르므로 사용할 모델의 가이드에서 확인합니다. 다음은 예시 모델 Seedance 2.5의 최소 요청 본문입니다.
{
"model": "dreamina-seedance-2.5",
"prompt": "바람에 천천히 흔들리는 초원의 풀을 고정 카메라로 촬영한 영상"
}다음은 위 예시 본문을 보내는 cURL과 Python 예시입니다. 서버 환경 변수 LETSUR_API_KEY를 준비합니다. 다른 모델을 호출하려면 cURL의 -d 또는 Python의 payload 본문을 그 모델 가이드의 형식으로 바꿉니다.
Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이나 서명 링크가 포함된 출력은 공개 로그에 남기지 마세요.
cURL
curl --fail-with-body "https://gw.letsur.ai/v1/video/generations" \
-H "Authorization: Bearer $LETSUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"dreamina-seedance-2.5","prompt":"바람에 천천히 흔들리는 초원의 풀"}'접수에 성공하면 게이트웨이가 HTTP 200과 작업 ID를 반환합니다. 접수 응답의 필드는 다음과 같습니다.
| 필드 | 설명 |
|---|---|
id | 문자열. 렛서 작업 ID lst-…. 모델과 관계없이 작업 ID는 이 필드에 있습니다 |
estimated_cost | 접수 응답에서는 null입니다. 이 값으로 비용이 확정됐다고 판단하지 않습니다 |
Response.TaskId | 문자열. 지원 모델에서 이 필드가 있는 모델의 응답에만 있습니다. 호환을 위해 id와 같은 값을 담습니다 |
다음은 설명용 응답입니다.
{"id": "lst-example-job-id", "estimated_cost": null}Response.TaskId가 있는 모델의 설명용 응답은 {"id": "lst-example-job-id", "Response": {"TaskId": "lst-example-job-id"}, "estimated_cost": null}입니다.
작업 ID를 저장한 뒤 작업 조회에 사용합니다. 작업 비용은 작업 조회의 usage에서 확인합니다. HTTP 200은 요청이 접수됐다는 뜻이며, 영상 생성이나 파일 준비가 끝났거나 비용이 확정됐다는 뜻은 아닙니다.
결과 보관 선택하기
게이트웨이는 생성된 결과 파일을 렛서 저장소에 복사합니다. 작업 조회와 Media Links에서 다운로드 링크를 받아 파일을 다운로드합니다. 공통 보관 및 삭제 조건은 이용약관 부속서 1 , 개인정보의 처리는 개인정보 처리방침 을 따릅니다.
보관 옵션 지정하기
결과를 받을 시점과 결과를 후속 작업에 사용할지에 맞춰 요청에 store_media를 명시하세요. 이 필드의 이름은 모든 모델에서 같습니다.
store_media | 보관 방식 |
|---|---|
false | 결과를 전달하기 위해 약 1시간 임시 보관합니다 |
true | 결과를 보관합니다. 나중에 받거나 다음 생성 요청의 입력으로 사용할 수 있습니다 |
| 생략 | 스페이스 설정을 따릅니다 |
이전 작업의 결과를 다음 생성 요청의 입력으로 사용하려면 이전 작업의 생성 요청에 store_media: true를 지정합니다. 결과를 입력으로 준비하는 순서는 결과를 다음 요청에 쓰기에서 확인합니다.
보관 기간과 링크 만료
store_media: false를 선택해도 결과 파일은 복사됩니다. 임시 보관 기간 약 1시간은 첫 파일 복사를 접수한 시점부터 계산하므로, 파일 준비가 끝난 뒤 1시간이 남는다고 보장하지 않습니다. 파일이 준비되면 즉시 다운로드하세요.
파일 보관과 다운로드 서명 링크는 따로 만료됩니다. 링크를 재발급해도 파일 보관 기간은 늘어나지 않습니다.
| 만료시각 | 확인할 곳 |
|---|---|
| 파일 보관 만료 | Media Links 응답의 expires_at. 작업 조회 응답의 미디어 항목에는 이 필드가 없습니다 |
| 다운로드 링크 만료 | url_expires_at |
파일 보관이 만료되면 새 링크를 발급할 수 없습니다. expires_at이 지났다고 해서 물리 삭제가 끝났다고 판단하지 않습니다.
store_media 옵션은 렛서가 복사한 결과 파일의 보관을 제어합니다. 참조 원본이나 공급사에 등록된 사본까지 같은 시점에 삭제한다는 의미는 아닙니다.
오류와 복구
접수 응답을 받지 못했다면 요청이 접수되지 않았다고 단정할 수 없습니다. 생성 POST를 자동으로 반복하면 별도 작업이 만들어질 수 있습니다.
| 상황 | 다음 행동 |
|---|---|
| 입력 오류로 거절됨 | 응답의 상세 내용을 확인하고 필드와 입력 조합을 수정합니다 |
| 대기열 한도로 거절됨 | Retry-After가 있으면 그 값을 따릅니다 |
| 인증 오류 또는 공통 오류 | 오류 처리를 확인합니다 |
| 이미 작업 ID를 받음 | 새 요청을 보내지 않고 같은 작업을 조회합니다 |
| 작업 ID도 받지 못함 | 다시 생성하지 않습니다. 스페이스 이름, 요청 시각, 모델 코드와 확보한 오류 코드를 기록한 뒤 접수 여부를 확인할 수 없을 때의 문의 방법에 따라 원래 요청의 처리 여부를 확인합니다 |
문의할 때 API 키나 전체 인증 헤더는 보내지 마세요.