Media Links

작업 결과의 미디어 ID로 다운로드 링크를 받으세요.

링크를 재발급해도 파일 보관기간은 늘어나지 않습니다.

POSThttps://gw.letsur.ai/v1/media/{media_id}/link

AUTHAuthorization: Bearer <API_KEY>

사용할 식별자와 인증

Seedance 영상의 작업 조회 응답에서 받은 data.job.result.media[].media_id를 사용합니다. 생성 접수의 작업 ID나 입력 업로드의 파일 ID를 넣는 곳이 아닙니다.

요청 URL은 https://gw.letsur.ai/v1/media/{media_id}/link입니다. 결과 파일과 같은 스페이스의 AI 게이트웨이 API 키로 인증하며 요청 본문은 필요 없습니다. 키와 헤더 설정은 인증과 요청 헤더를 확인합니다.

발급 응답

HTTP 200 응답은 최상위에 다음 필드를 반환합니다. 아래 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`	그대로 열거나 다운로드할 서명 링크
`url_expires_at`	링크 만료시각. Unix 초
`expires_at`	파일 보관 만료시각. ISO 형식 또는 `null`
`state`	발급 성공 시 `stored`. 작업 조회의 `ready`와 표기가 다름
`content_type`, `size_bytes`	파일의 MIME 타입과 바이트 크기

새 링크의 만료는 링크 유효기간과 파일 보관 만료 중 먼저 도달하는 시각을 넘지 않습니다. 링크를 재발급해도 파일 보관기간은 늘어나지 않습니다. 파일 만료는 물리 삭제가 완료됐다는 증거가 아닙니다.

발급 요청의 오류

아래 오류는 링크 발급 POST 응답입니다. 최상위 error 객체에 code, message가 있으며 파일 상태에 따라 state나 source_url이 추가될 수 있습니다.

HTTP	`error.code`	다음 행동
404	`MEDIA_NOT_FOUND`	미디어 ID와 API 키의 스페이스 확인
503	`MEDIA_NOT_READY`	파일 준비 중. `Retry-After`에 따라 같은 ID로 재요청
503	`MEDIA_UNAVAILABLE`	링크 발급을 지금 사용할 수 없음. 잠시 후 재시도 또는 지원 요청
410	`MEDIA_RETENTION_EXPIRED`	파일 보관 만료로 새 링크를 발급할 수 없음
502	`MEDIA_NOT_STORED`	파일 사본을 사용할 수 없음. 오류 정보와 작업 ID로 지원 요청

MEDIA_NOT_STORED의 error.source_url이 있어도 공급자 원본 URL이 현재 유효하다는 보장은 없습니다.

발급된 링크로 파일을 받을 때

응답의 url을 그대로 사용하고 리다이렉트를 따라 파일을 받습니다. URL을 직접 조립하거나 쿼리의 서명 값을 바꾸지 않습니다. 이 다운로드에는 URL 서명을 사용하므로 AI 게이트웨이 API 키 헤더를 추가할 필요가 없습니다. 서명 링크도 접근 권한을 가지므로 공개 로그나 문의 본문에 남기지 않습니다.

게이트웨이는 준비된 파일에 대해 HTTP 302로 다운로드 위치를 안내합니다. 최종 파일 응답까지 받아야 다운로드가 완료됩니다.

링크를 열었을 때	의미와 다음 행동
410 `MEDIA_LINK_EXPIRED`	링크 서명이 만료됨. 파일이 유효하면 같은 미디어 ID로 링크 재발급
404 `MEDIA_NOT_FOUND`	ID 또는 서명이 잘못됨. 받은 URL을 그대로 썼는지 확인
503 `MEDIA_NOT_READY`	파일 준비 중. `Retry-After`를 따른 뒤 다시 확인
503 `MEDIA_UNAVAILABLE`	다운로드를 지금 사용할 수 없음. 잠시 후 재시도
502 `MEDIA_NOT_STORED`	파일 사본 사용 불가. 작업 ID와 오류 정보로 지원 요청

위 표는 게이트웨이 링크를 열었을 때의 오류입니다. 리다이렉트 뒤 저장소 응답은 형식이 다를 수 있습니다. 링크의 MEDIA_LINK_EXPIRED와 발급 POST의 MEDIA_RETENTION_EXPIRED를 구분하세요. 파일 수령까지의 순서는 영상 생성하고 파일 받기를 확인합니다.