AI 생성 파일 저장: PiAPI 출력 URL에서 영구 저장소까지

생성 작업이 완료되면 결과를 얻지만 공급자가 호스팅하는 URL이 영구 미디어 보관소인 것은 아닙니다. 사용자가 나중에 열거나 편집하거나 내려받아야 한다면 직접 관리하는 저장소로 파일을 복사하고 생성과 별도로 복사 상태를 추적하세요.

1. 사용한 모델에 맞게 출력 읽기

저장한 작업 ID를 조회하고 data.status가 completed인지 확인한 뒤 파일을 추출하세요. data.output 구조는 모델과 작업 유형에 따라 다릅니다. 해당 조회 예제를 참고하고 모든 응답에 동일한 최상위 이미지 또는 동영상 URL이 있다고 가정하지 마세요.

예를 들어 Kling 문서의 응답에는 동영상 리소스가 포함된 works 배열이 있습니다. 다른 모델은 다른 필드를 사용합니다. 작업 ID, 모델, 작업 유형, 완료 시각, 선택한 리소스 인덱스를 자체 작업과 함께 저장하면 재시도 시 같은 결과를 찾을 수 있습니다.

2. 즉시 복사하고 서비스별 보관 기간 확인하기

PiAPI의 출력 저장 문서는 서비스와 호스팅 위치별로 다른 보관 규칙을 설명합니다. 일부는 짧은 기간을 명시하고 일부는 공급자의 CDN 정책을 따르며, 예전 서비스도 포함합니다. 한 항목의 기간을 모든 현재 모델에 적용하거나 명시되지 않은 기간을 무제한으로 해석하지 마세요.

완료 후 Webhook 또는 폴링 흐름으로 백그라운드 복사를 시작하세요. 콜백 응답 전에 작업을 영구 저장합니다. 아래는 앱 상태 흐름의 예이며, 이 저장 상태는 PiAPI 작업 API가 아닌 자체 앱의 상태입니다.

generation completed → copy queued → downloading → verified → saved
                                      ↘ copy failed → retry copy

3. 저장 완료 표시 전에 실제 바이트 검증하기

결과 URL에서 다운로드할 때 PiAPI API 키를 전달하지 마세요. 허용 목적지를 제한하고 리디렉션을 검증하며 크기와 시간 제한을 설정합니다. HTTP 상태, 실제 바이트 수, 예상 미디어 유형과 기본 읽기 가능 여부를 확인하세요. 200을 반환하는 HTML 오류 페이지는 저장된 동영상이 아닙니다.

임시 객체에 기록하고 체크섬을 계산한 뒤 검증이 성공해야 최종 객체를 공개하세요. 작업 ID와 리소스 인덱스에 기반한 고정 키를 사용합니다. 객체 키, 바이트 수, 체크섬과 저장 시각을 기록하고 접근 정책에 맞는 자체 관리 URL을 제공하세요.

4. 저장 재시도와 생성 재시도 분리하기

복사가 실패해도 생성 상태는 완료로 유지하고 원본이 유효한 동안 복사만 재시도하세요. 영구 고유 레코드로 중복 이벤트가 미디어를 중복 등록하지 못하게 합니다. URL을 읽을 수 없으면 작업을 다시 조회하고 현재 출력을 확인하되, 만료된 파일 복구가 보장되지는 않습니다. 배포 전 중복 이벤트, 부분 다운로드, 사용할 수 없는 URL을 시험하세요.

참고: 출력 저장, Kling 작업 조회, Webhook. 이는 앱의 저장 설계이며 PiAPI의 장기 보관 약속이 아닙니다.