References

업로드가 필요한 경우

Seedance 영상 생성 요청에 로컬 이미지, 영상 또는 오디오를 참조로 넣으려면 먼저 파일을 업로드할 수 있습니다. 텍스트만으로 생성하거나 지원되는 외부 URL을 직접 쓰는 요청에는 이 단계가 필요 없습니다. 반환 참조를 넣을 위치와 조합은 Video Generations를 확인합니다.

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

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

기본 업로드는 일반 파일 참조를 반환합니다. 공급사 자산 등록이 필요한 Seedance 입력은 POST /v1/references?track=managed로 업로드합니다. track은 file 또는 managed이며 다른 값은 요청 오류입니다. managed에도 아래 이미지, 영상과 오디오 형식 및 크기 제한이 적용됩니다.

관리형 업로드는 reference를 letsur-asset://example-file-id 형태로 반환하며 track은 managed입니다. 일반 업로드의 참조는 letsur-file://example-file-id이며 track은 file입니다. 반환된 참조를 그대로 생성 입력에 사용하세요. 공급사 등록은 해당 참조로 생성할 때 진행되므로 업로드 응답만으로 등록 완료를 판단하지 않습니다. 사용 조건과 콘텐츠 심사는 Seedance 2.5를 확인합니다.

파일 입력과 제한

multipart/form-data의 필수 file 파트에 파일 바이트와 MIME 타입을 지정합니다. JSON에 파일 URL을 넣는 방식이 아닙니다.

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

요청과 응답 예시

다음은 Bash 또는 zsh와 cURL에서 실행하는 업로드 요청입니다. 서버 환경 변수 LETSUR_API_KEY와 현재 디렉터리의 reference.mp4가 필요합니다. 키 준비는 첫 API 호출을 따릅니다.

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl --fail-with-body https://gw.letsur.ai/v1/references \
    --header @- \
    -F 'file=@reference.mp4;type=video/mp4' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

성공하면 HTTP 200과 다음 형태의 응답을 반환합니다. 식별자와 크기는 설명용입니다.

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

reference를 생성 요청의 해당 URL 입력에 그대로 사용합니다. bytes는 업로드된 크기이며 null일 수 있습니다. 응답은 공개 다운로드 URL이나 보관 만료시각을 제공하지 않습니다. 별도 업로드 파일은 생성 작업이 끝나는 시점에 맞춰 지우는 임시 입력과 다르지만 영구 보관을 뜻하지 않습니다.

업로드 오류

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

파일 종류별 크기 제한 초과가 모두 413을 반환하는 것은 아닙니다. 필수 file 파트 누락은 요청 형식 검증 오류이므로 multipart 구성을 확인합니다.