Media Links
결과 미디어의 다운로드 링크 발급
미디어 ID로 링크를 발급받는 요청과 응답, 파일 다운로드 방법을 설명하고, 링크와 파일의 만료 조건 및 단계별 오류를 구분합니다.
페이지 목차
https://gw.letsur.ai/v1/media/{media_id}/linkAuthorization: Bearer <API_KEY>사용할 식별자와 인증
이 엔드포인트로 렛서 저장소에 복사된 결과 파일의 다운로드 링크를 발급받습니다. 링크를 받아 파일을 다운로드하는 순서는 생성 요청하고 결과 파일 받기의 영상 결과 받기에서 확인합니다.
영상 생성 작업의 작업 조회 응답에서 받은 data.job.result.media[].media_id를 사용합니다. 이 요청에는 생성 접수 응답의 작업 ID나 입력 파일 업로드 응답의 파일 ID를 사용하지 않습니다.
요청 URL은 https://gw.letsur.ai/v1/media/{media_id}/link입니다. 결과 파일과 같은 스페이스의 AI 게이트웨이 API 키로 인증합니다. 요청 본문은 필요 없습니다. 키와 헤더 설정은 인증과 요청 헤더에서 확인합니다.
링크 발급 요청 예시
cURL과 Python 예제는 서버 환경 변수 LETSUR_API_KEY와 작업 조회에서 받은 미디어 ID를 저장한 환경 변수 MEDIA_ID를 사용합니다.
Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이나 서명 링크가 포함된 출력은 공개 로그에 남기지 마세요.
cURL
curl --fail-with-body -X POST "https://gw.letsur.ai/v1/media/$MEDIA_ID/link" \
-H "Authorization: Bearer $LETSUR_API_KEY"반환된 url로 파일을 받기 전에 다음 절의 링크 만료시각과 파일 만료시각을 확인합니다. 다운로드 방법은 발급된 링크로 파일을 받을 때에 있습니다.
발급 응답
HTTP 200 응답의 최상위에는 다음 필드가 포함됩니다.
| 필드 | 설명 |
|---|---|
media_id | 문자열. 요청한 미디어 ID |
url | 문자열. 그대로 열거나 다운로드할 서명 링크 |
url_expires_at | 정수. 링크 만료시각(Unix 초) |
expires_at | 문자열 또는 null. 파일 보관 만료시각(ISO 형식) |
state | 문자열. 발급에 성공하면 stored. 작업 조회의 ready와 표기가 다름 |
content_type | 문자열. 파일의 MIME 타입 |
size_bytes | 정수. 파일의 바이트 크기 |
다음은 설명용 응답입니다. 아래 URL과 시각은 설명용이며, 예시 URL로 실제 파일을 받을 수는 없습니다.
{
"media_id": "example-media-id",
"url": "https://gw.letsur.ai/example-signed-download-url",
"url_expires_at": 1789092000,
"expires_at": "2026-09-12T02:00:00Z",
"state": "stored",
"content_type": "video/mp4",
"size_bytes": 1048576
}링크와 파일은 각각 만료됩니다. 두 만료시각은 형식도 다릅니다. url_expires_at은 Unix 초 정수이고 expires_at은 ISO 형식 문자열입니다. 각 만료시각이 지났을 때 링크를 사용할 수 있는지는 다음과 같습니다.
| 상황 | 결과 |
|---|---|
url_expires_at이 지남 | 링크는 정해진 유효기간을 넘겨 사용할 수 없음. 파일이 유효하면 같은 미디어 ID로 새 링크를 발급 |
expires_at이 지남 | 파일 보관이 만료됨. url_expires_at이 남아 있어도 링크를 사용할 수 없음. 물리 삭제가 완료됐다는 증거는 아님 |
링크를 재발급해도 파일 보관 기간은 늘어나지 않습니다. 보관 기간과 store_media에 따른 보관 방식은 Video Generations의 결과 보관 선택하기에서 확인합니다. 공통 보관 및 삭제 조건은 이용약관 부속서 1 을 따릅니다.
발급 요청의 오류
아래 오류는 링크 발급 POST에서 반환됩니다. 최상위 error 객체에 code, message가 있으며 파일 상태에 따라 state나 source_url이 추가될 수 있습니다.
| 오류 | 원인과 할 일 |
|---|---|
MEDIA_NOT_FOUND (404) | 미디어 ID와 API 키의 스페이스를 확인합니다 |
MEDIA_NOT_READY (503) | 파일 준비 중입니다. Retry-After에 따라 같은 ID로 다시 요청합니다 |
MEDIA_UNAVAILABLE (503) | 링크 발급을 일시적으로 사용할 수 없습니다. 잠시 후 재시도하거나 지원을 요청합니다 |
MEDIA_RETENTION_EXPIRED (410) | 파일 보관이 만료되어 새 링크를 발급할 수 없습니다. 이미 받은 사본을 확인하거나 문의합니다 |
MEDIA_NOT_STORED (502) | 파일 사본을 사용할 수 없습니다. 오류 정보와 작업 ID로 지원을 요청합니다 |
MEDIA_NOT_STORED 응답에 error.source_url이 있어도 그 공급사 원본 URL이 현재 유효하다고 보장되지 않습니다.
발급된 링크로 파일을 받을 때
- 응답의
url을 그대로 씁니다. URL을 직접 조립하거나 쿼리의 서명 값을 바꾸지 마세요. - 이 다운로드는 URL 서명으로 인증하므로 AI 게이트웨이 API 키 헤더를 넣지 마세요.
- 서명 링크만 있으면 다른 사람도 파일에 접근할 수 있습니다. 링크를 공개 로그나 문의 본문에 남기지 마세요.
게이트웨이는 파일이 준비되어 있으면 HTTP 302로 다운로드 위치를 알려 줍니다. 리다이렉트를 따라가 최종 파일 응답까지 받아야 다운로드가 끝나므로, cURL에서는 -L 옵션을 붙입니다. MEDIA_URL에는 발급 응답의 url을 넣습니다.
curl --fail-with-body -L -o result.mp4 "$MEDIA_URL"게이트웨이 링크에 접근할 때 반환될 수 있는 오류는 다음과 같습니다. 리다이렉트된 뒤 저장소가 보내는 응답은 형식이 다를 수 있습니다.
| 오류 | 원인과 할 일 |
|---|---|
MEDIA_LINK_EXPIRED (410) | 링크 서명이 만료됐습니다. 파일이 유효하면 같은 미디어 ID로 링크를 다시 발급받습니다 |
MEDIA_NOT_FOUND (404) | ID 또는 서명이 잘못됐습니다. 발급받은 URL을 바꾸지 않고 사용했는지 확인합니다 |
MEDIA_NOT_READY (503) | 파일 준비 중입니다. Retry-After를 따른 뒤 다시 확인합니다 |
MEDIA_UNAVAILABLE (503) | 다운로드를 일시적으로 사용할 수 없습니다. 잠시 후 재시도합니다 |
MEDIA_NOT_STORED (502) | 파일 사본을 사용할 수 없습니다. 작업 ID와 오류 정보로 지원을 요청합니다 |
링크의 MEDIA_LINK_EXPIRED와 발급 POST의 MEDIA_RETENTION_EXPIRED를 구분하세요.