검토 2026-11-10 · API 버전 2026-11-09 · Markdown 읽기
미디어 업로드와 보관
미디어 바이트는 임시 비공개 오브젝트 스토리지로 직접 전달돼요. REST와 MCP는
업로드 지시를 반환할 뿐, 도구 JSON으로 바이너리 파일 콘텐츠를 받지 않아요.
배포에 스토리지가 설정되어 있어야 하고, 그렇지 않으면 업로드 생성이
provider_unavailable을 반환해요.
업로드 수명 주기
- filename, 선언된 MIME, 바이트 수로
POST /api/v1/media/upload-intents를 호출하세요. 반환된assetId와sessionId를 별개의 식별자로 저장하세요. method를 확인하세요.presigned_put이면 반환된 헤더를 사용해 전체 파일을uploadUrl에 업로드하세요.multipart_initiated이면partSizeBytes로 분할하고, 번호가 매겨진 각 파트를 반환된 URL에 업로드한 후 ETag 영수증을 보관하세요. 스토리지 요청에 AiVideoEditor bearer 키를 절대 추가하지 마세요.sessionId와, 멀티파트라면 각partNumber와etag가 담긴multipart.parts로POST /api/v1/media/{assetId}/finalize에서 확정하세요.- 확정된 asset ID를 초안의
mediaIds에 사용하세요. 업로드 인텐트만으로는 asset이 게시 가능해지지 않아요.
서버는 불변인 최종 사본에서 실제 바이트와 형식을 관찰해요. 선언된 크기/MIME은 예약 입력일 뿐 파일 유효성의 증거가 아니에요. 지원되는 기본 계열은 JPEG, PNG, MP4이고, 개별 수신처는 더 엄격한 제한을 둘 수 있어요. 현재 최대 파일 크기는 500 MiB(524,288,000바이트)예요. 50 MiB 이상 파일은 멀티파트를 사용하고, 보통 16 MiB 파트를 써요. 항상 이 기본값에서 유추하지 말고 반환된 크기, URL, 만료를 따르세요.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
멀티파트 형태 예시예요; 실제 모든 파트를 포함하세요. 단일 PUT 확정은 sessionId만
보내요. 각 새 API 변경 작업에는 고유한 Idempotency-Key를 부여하고, 안전한 동일
재시도를 위해 보관하세요.
재개 또는 포기
만료된 서명된 URL은 영구 미디어 주소가 아니에요. fromPart과 toPart(최대
64개 파트의 포함 범위)로 POST /media/{id}/upload-parts을 호출해 새 멀티파트
파트 URL을 요청하세요. 제한된 요청 형태는 API reference를 참고하세요.
완료된 파트를 불필요하게 다시 업로드하거나 스토리지를 통해 직접 멀티파트 조립을
완성하지 마세요: 확정은 서버가 제어해요.
불완전한 업로드를 취소할 때는 POST /media/{id}/abandon을 사용하세요. 공유
정리 워크플로를 통해 예약을 해제해요. 세션 만료나 소비된 멀티파트 상태에는 새
인텐트가 필요할 수 있어요; 스토리지 오브젝트 키를 추측하지 마세요.
임시 보관
GET /media/{id}는 상태와 동적 deleteAfter 정보를 반환하지, 영구 공개 URL은
반환하지 않아요. 예약되었거나 진행 중인 사용은 작업이 끝날 때까지 미디어를
보호해요. 기본 정책은 미사용 초안 미디어를 14일, 완료된 미디어를 72시간,
실패했거나 모호한 작업을 관련 시도 후 7일간 유지해요. 실제 보관 기간은 남은 모든
참조에 따라 달라요; deleteAfter는 null일 수 있어요. 원본을 보관하세요. 미디어가
만료되었거나 삭제 중이면 게시 전에 다시 업로드하세요.