본문으로 건너뛰기

References

영상 생성 입력으로 사용할 파일 업로드

multipart/form-data 업로드의 파일 조건과 일반 및 관리형 참조를 설명하고, 반환된 참조를 생성 요청에 사용하는 방법을 안내합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/references
인증Authorization: Bearer <API_KEY>

업로드가 필요한 경우

이 엔드포인트로 영상 생성 요청에 참조로 사용할 로컬 이미지, 영상 또는 오디오를 먼저 업로드할 수 있습니다. 텍스트만으로 생성하거나 지원되는 외부 URL을 직접 지정하는 요청에는 이 단계가 필요 없습니다. 앞 작업의 결과를 받아 다음 요청의 입력으로 사용하는 순서는 생성 요청하고 결과 파일 받기의 결과를 다음 요청에 쓰기에서 확인합니다.

업로드 응답의 참조를 어느 필드에 지정하는지, 다른 입력과 어떻게 조합하는지는 모델마다 다릅니다. 사용할 모델의 가이드를 지원 모델에서 확인하세요.

요청 URL은 https://gw.letsur.ai/v1/references입니다. 파일은 AI 게이트웨이 API 키에 연결된 스페이스에 업로드되므로 본문에 space_id를 보내지 않습니다. 공통 설정은 인증과 요청 헤더에서 확인합니다.

지원 모델

모델참조를 지정하는 필드와 입력 조합관리형 참조
Seedance 2.5입력 방식 선택하기받음. 인물이 포함된 참조 준비하기
Seedance 2.0 계열참조 조건받음
Kling참조 입력과 영상 편집받지 않음. 일반 업로드만 사용

일반 파일과 관리형 참조 선택하기

관리형 참조는 공급사 자산 등록이 필요한 입력에만 사용하며, 관리형 참조를 받는 모델에서만 쓸 수 있습니다. 관리형 참조를 받지 않는 모델에 입력할 파일은 일반 업로드로 올립니다. 모델별 지원 여부는 지원 모델에서 확인합니다. 기본 업로드에서는 일반 파일 참조가 반환됩니다.

두 방식의 요청과 응답 값은 다음과 같습니다.

  • 일반 파일 참조: POST /v1/references로 요청합니다. 응답의 track은 file이고, reference는 letsur-file://example-file-id 형태로 반환됩니다.
  • 관리형 참조: POST /v1/references?track=managed로 요청합니다. 응답의 track은 managed이고, reference는 letsur-asset://example-file-id 형태로 반환됩니다.

managed로 업로드할 때도 아래의 이미지, 영상과 오디오 형식 및 크기 제한이 적용됩니다.

반환된 참조를 그대로 생성 입력에 사용하세요. 관리형 참조는 그 참조로 생성을 요청할 때 공급사에 등록되므로 업로드 응답만으로 등록이 완료됐다고 판단하지 않습니다. 관리형 참조의 사용 조건과 콘텐츠 심사는 관리형 참조를 받는 모델의 가이드에서 확인합니다.

파일 입력과 제한

multipart/form-data의 필수 file 파트에 파일 바이트를 포함하고 MIME 타입을 지정합니다. JSON 본문에 파일 URL을 지정하는 방식은 지원되지 않습니다.

필드타입요구 여부설명
filemultipart 파트필수업로드할 파일의 바이트와 MIME 타입
trackstring (쿼리 매개변수)선택file 또는 managed. 생략하면 일반 파일 참조를 반환. 다른 값은 요청 오류

파일 종류마다 허용하는 MIME 타입과 크기 상한은 다음과 같습니다.

종류허용 MIME 타입파일 크기 상한
이미지image/png, image/jpeg, image/jpg, image/webp, image/gif, image/bmp, image/tiff, image/heic, image/heif30 MiB
영상video/mp4, video/quicktime200 MiB
오디오audio/wav, audio/x-wav, audio/wave, audio/mpeg, audio/mp315 MiB

1 MiB는 1,048,576바이트입니다. 이 크기 제한을 통과해도 생성 모델이 정한 영상 길이, 해상도, FPS 또는 콘텐츠 조건에 따라 입력이 거절될 수 있습니다. 확장자를 바꿔도 파일 형식은 바뀌지 않습니다.

요청과 응답 예시

다음은 cURL이나 Python에서 실행하는 업로드 요청입니다. 서버 환경 변수 LETSUR_API_KEY와 현재 디렉터리의 reference.mp4가 필요합니다. 키를 준비하는 방법은 첫 API 호출에서 확인합니다.

Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이나 서명 링크가 포함된 출력은 공개 로그에 남기지 마세요.

cURL
curl --fail-with-body https://gw.letsur.ai/v1/references \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -F 'file=@reference.mp4;type=video/mp4'

업로드에 성공하면 게이트웨이가 HTTP 200과 다음 필드를 반환합니다.

필드설명
file_id문자열. 생성 입력 파일의 식별자
reference문자열. 생성 요청의 URL 입력에 지정할 참조. letsur-file://… 또는 letsur-asset://… 형태
bytes정수 또는 null. 업로드한 파일의 바이트 크기
track문자열. file 또는 managed

다음은 설명용 응답이며, 식별자와 크기는 실제 값이 아닙니다.

{ "file_id": "example-file-id", "reference": "letsur-file://example-file-id", "bytes": 1048576, "track": "file" }

file_id는 생성 결과의 media_id, Batch 입력과 결과의 파일 ID와 다른 값입니다. 서로 바꿔 넣지 마세요.

생성 요청의 URL 입력에는 반환된 reference 전체 값을 그대로 사용합니다. 이 참조로 영상을 생성할 때 사용할 필드와 입력 조합은 지원 모델에 연결한 모델별 가이드에서 확인합니다.

응답에는 공개 다운로드 URL과 보관 만료시각이 없습니다.

참조 파일의 보관과 삭제 문의

업로드한 참조 파일은 생성 작업이 끝날 때 삭제되는 임시 입력과 보관 방식이 다릅니다. 다만 영구 보관이 보장되지 않으므로 원본은 별도로 보관하세요. 참조 파일에도 생성 결과의 store_media 보관 설정이 적용된다고 가정하지 않습니다.

보관 조건의 확인이나 파일 삭제를 요청하려면 플랫폼 내 문의 기능에 다음 정보를 남기세요.

  • 파일 ID
  • 요청 사항

파일 원문이나 API 키는 보내지 마세요. 렛서는 요청 권한과 적용 조건을 확인해 가능한 조치와 처리 결과를 안내합니다. 렛서에 파일 삭제를 요청해도 그 요청만으로 공급사에 등록된 사본의 삭제가 완료되지는 않습니다. 공통 처리 조건과 요청 절차는 이용약관 제13조 및 부속서 1 , 개인정보에 관한 권리 행사는 개인정보 처리방침 제8조 를 따릅니다.

오류와 복구

오류 응답의 최상위 error.code와 error.message를 확인합니다.

오류원인과 할 일
REFERENCE_UPLOAD_REJECTED (400)MIME 타입, 종류별 크기 제한과 오류 상세를 확인합니다
REFERENCE_TOO_LARGE (413)전체 파일의 200 MiB 상한을 초과했는지 확인합니다
REFERENCE_UPLOAD_UNAVAILABLE (503)업로드를 일시적으로 사용할 수 없습니다. 잠시 후 재시도하거나 지원을 요청합니다

파일 종류별 크기 제한을 초과해도 항상 413이 반환되지는 않습니다. 필수 file 파트가 빠지면 요청 형식 검증 오류가 반환되므로 multipart 구성을 확인합니다.