무검열 AI 이미지 또는 영상 제품을 개발한다면 세 가지 사실이 저장 설계를 결정합니다. 업로드한 레퍼런스 파일은 1일 동안 유지됩니다. API, SDK, Playground 작업으로 생성한 미디어는 약 14일 동안 유지됩니다(Studio 단편 영화 미디어에는 약 60일의 별도 상한이 있습니다). 전달받는 모든 다운로드 링크는 약 20분 동안만 작동합니다. 모두 최대 기간입니다. 계정 전체나 요청 하나에 대해 기간을 줄일 수만 있으며, 완료된 작업의 내용은 원할 때 삭제할 수 있습니다. 어떤 설정으로도 상한을 늘릴 수는 없습니다.
따라서 안정적인 방식은 유효 기간이 짧은 티켓으로 직접 업로드하고, 파일을 확정한 뒤, 비공개 spicy:// 레퍼런스로 비동기 작업을 제출하고, 작업이 끝나면 결과 링크를 받아 자신이 관리하는 저장소에 복사하거나 의도적으로 만료되도록 두는 것입니다. 고객의 업로드를 공개 버킷에 두거나 반환된 다운로드 URL을 영구적인 링크처럼 저장하지 마세요.
SpicyAPI에 레퍼런스를 업로드하는 것은 무료이며, 이를 사용하는 생성 작업은 별도로 과금됩니다. 기존 결과의 다운로드 링크를 갱신해도 생성을 다시 실행하거나 구매하지 않습니다. 새로운 생성 시도에는 해당 모델의 비용이 별도로 들고, 자신의 버킷에 보관하는 사본의 저장, 요청, 전송에는 저장소 제공업체의 요금이 적용됩니다.
고객에게 저장 기간을 약속하기 전에 수락된 보관 기한을 확인하세요. 보관 문서에서 설정을 설명합니다. 로컬 복사의 실용적인 예는 임시 AI 미디어를 오래 사용할 제품 자산으로 전환하기에 있습니다.
먼저 Playground에서 사용해 보기
- z-image 텍스트→이미지 페이지를 열고 Workbench의 Form에서 Prompt를 입력한 뒤 Aspect ratio를 선택하고 Run model을 누르세요(먼저 로그인해야 하며, 이 이미지 한 장은 일반적인 유료 생성입니다). Preview에서 확인하고 Download로 저장하세요.
- Console에서 Logs를 열고 해당 작업을 찾아 출력이 얼마나 오래 유지되는지 확인하세요.
- Data protection에서 Retention을 열어 네 가지 보관 기간을 확인하고 필요한 기간을 줄이세요.
- 자신의 사본을 확보했다면 완료된 작업에서 Destroy outputs를 선택해 내용을 삭제하세요.
SpicyAPI가 보관하는 데이터와 기간
| 데이터 | 보관 기간 | 만료 시 동작 |
|---|---|---|
| 업로드한 레퍼런스 파일 | 확정 처리 성공 후 1일 | spicy:// URI는 재시도를 포함한 새 작업에서 사용할 수 없으며, 이후 객체가 삭제됩니다. 정리에는 최대 24시간의 지연이 있습니다 |
| 생성된 이미지, 영상, 오디오 | API, SDK, Playground 결과는 약 14일, Spicy Studio 단편 영화 프로젝트 안에서는 약 60일이며, 정리에 최대 24시간의 지연이 있습니다 | 객체 저장소에서 삭제되며 다운로드 링크를 발급할 수 없습니다 |
작업의 프롬프트 텍스트와 결과 파일 경로(input, output) | 30일 | 두 필드가 비워지며 작업 행은 남습니다 |
| 작업 기록(ID, 모델, 상태, 금액, 타임스탬프) | 무기한 | 과금 증빙으로 유지되며, 내용 필드는 각자의 일정에 따라 비워집니다 |
| 과금 원장 | 미국 세법·회계법이 요구하는 기간(연 단위) | 유지되며 내용 삭제의 영향을 받지 않습니다 |
| 작업 로그와 Webhook 전달 기록 | 최소 60일 | 삭제됩니다 |
| 데이터베이스 백업 | 35일 | 순차 교체됩니다. 내용을 삭제해도 백업이 즉시 지워지지는 않습니다 |
직접 기간을 줄이거나 내용 삭제하기
1. 계정 보관 기간. 콘솔의 Data protection 페이지에서 Retention을 열면 별개의 네 가지 기간이 있습니다.
| 기간 | 대상 | 기본값 | 더 짧은 옵션 |
|---|---|---|---|
| Generated results | 이미지, 영상, 오디오 및 결과 페이로드 | 약 14일 | 1시간, 6시간, 24시간, 7일 |
| Short-film media | Studio 단편 영화 미디어 및 내보낸 영화 | 약 60일 | 1시간부터 30일까지 |
| Prompt text | 요청의 텍스트 필드 | 30일 | 결과와 동일, 1시간, 24시간, 7일 |
| Uploaded files | 레퍼런스 파일 | 1일 | Delete when the job ends |
업로드 파일의 보관 기간에는 세 가지 중요한 제한이 있습니다.
- Delete when the job ends: 업로드를 사용하는 모든 작업이 최종 상태가 되면 일반적으로 1분 안에 업로드가 삭제됩니다. 삭제된 레퍼런스로 새로 생성하려면 다시 업로드해야 합니다.
- 기존 파일만 적용: 이 설정은 저장 시점에 존재하는 파일에 적용됩니다. 이후 업로드는 현재 확정 응답에 표시된 기본 1일 만료 기간을 유지합니다.
- 1시간 및 24시간 옵션: 현재 아무것도 변경하지 않으며, 업로드는 반환된
expiresAt까지 사용할 수 있습니다.
기간을 줄이기 전에 주의하세요: 더 짧은 설정은 이미 실행한 작업에도 소급 적용될 수 있습니다. 예를 들어 Prompt text를 1시간 또는 24시간으로 설정하면 Generated results가 14일이어도 완료된 지 하루가 넘은 모든 작업의 프롬프트 텍스트와 생성 결과가 삭제됩니다. 삭제된 내용은 복구할 수 없습니다. 보관할 것은 먼저 다운로드하세요. 설정 기간을 늘려도 앞으로의 보관에만 영향을 줍니다.
2. 요청별 설정. 작업을 만들 때 X-Spicy-Retention 헤더를 초 단위로 보내세요. 보관 문서에 요청 예가 있습니다. 실제 기간은 요청, 계정 설정, 플랫폼 상한 중 가장 짧은 기간입니다. 요청한 기간을 약속하지 말고 작업에서 수락된 기한을 확인하세요.
전달이나 저장된 라이브러리를 약속하는 제품에서는 즉시 삭제를 사용하지 마세요. 사본 복사가 끝나기 전에 결과를 제거할 수 있습니다. 전달 후 복구를 위한 여유를 두세요.
3. 완료된 작업의 내용 삭제. 필요한 것을 복사했거나 고객이 삭제를 요청하면 해당 작업의 창작 내용을 제거하세요.
콘솔은 Logs의 작업에서 같은 기능을 Destroy outputs로 제공합니다. 세 가지 규칙이 적용됩니다.
- 완료된 작업만 가능. Purge는
taskId별로 멱등적이며Idempotency-Key가 필요 없습니다. 생성을 취소하거나 요금을 환불하지 않으며billingRetained는 true로 유지됩니다. - 삭제는 예약됩니다.
contentState는purged가 되지만, 일반적으로 1분 안에 정리가 끝날 때까지mediaDeletionPending은 true입니다. 고객에게 데이터가 사라졌다고 알리기 전에 완료를 확인하세요. present응답은 아무것도 삭제하지 않았습니다. 삭제 완료를 보고하지 말고 응답과 보존 설정을 조사하세요.
보관 기간에 따라 내용이 삭제되면 contentState는 expired이고, 직접 삭제했다면 purged입니다. 작업 상태의 expired는 전혀 다릅니다. 생성이 시간 초과되어 아무것도 만들지 못했다는 뜻입니다. 재시도는 두 번째 경우에만 도움이 됩니다.
레퍼런스 파일 보내기
레퍼런스 이미지, 영상 또는 오디오 파일은 세 가지 방법으로 작업에 전달할 수 있습니다. 공개 HTTPS URL은 파일 자체를 반환해야 합니다. 공유 페이지 링크(클라우드 드라이브, 사진 앨범, 소셜 게시물)는 웹페이지를 반환하므로 작업이 invalid_asset로 실패합니다. 이 경우 파일을 다운로드한 후 업로드하세요. 작은 이미지(최대 1 MiB)는 base64 데이터 URI로 인라인에 넣을 수 있습니다. 비공개이거나 큰 파일은 SDK, CLI 또는 Playground로 업로드해야 하며, 작업에서 사용할 비공개 spicy:// 레퍼런스가 반환됩니다.
업로드 한도는 JPEG, PNG, WebP, GIF의 경우 10 MiB, WAV, MP3, WebM, MP4, MOV의 경우 90 MiB 및 600초입니다. 모델이 더 작은 한도만 허용할 수도 있습니다. 하루의 유효 기간 이후에도 입력이 다시 필요하다면 원본 사본을 보관하세요. 백엔드는 업로드를 승인하고 소유자를 기록하기만 하면 되며 클라이언트가 바이트를 직접 보낼 수 있습니다. 업로드는 무료이고 생성은 별도 구매입니다. 미디어 문서에서 흐름을 설명합니다.
결과: 가져온 뒤 복사하거나 만료시키기
원고와 풍경 프레임이 하나의 투사된 장면으로 모입니다.
각 새 요청에 고유한 멱등성 키를 사용하고 작업 ID를 보관한 뒤 폴링이나 콜백으로 결과를 가져오세요. 준비된 자산에는 서명된 url이 있습니다. API 키 없이 가져오고 User-Agent를 Mozilla/5.0 등으로 지정해 보내세요. CDN은 Python urllib의 기본 에이전트를 403으로 거부하며, 이 응답은 링크 만료를 의미하지 않습니다. succeeded 작업에도 pending 자산이 있을 수 있으므로 URL이 준비될 때까지 계속 확인하세요. 만료된 링크는 보관 기간 안에서 갱신할 수 있습니다. 미디어 문서에서 방법을 설명합니다.
자산의 세 가지 상태를 명시적으로 처리하는 것이 좋습니다.
| 보이는 상태 | 의미 | 조치 |
|---|---|---|
pending: true, 아직 url 없음 | 파일이 저장소로 복사되는 중 | 몇 초 후 다시 조회 |
unavailable: true, key 없음 | 플랫폼에서 가져올 자산이 없음: 초기 저장 실패, 보관 종료 또는 Purge 삭제 | 저장하고 검증한 사본을 복구하고, 없다면 새 생성 여부를 명시적으로 결정 |
HTTP 410 응답(download-url) | 플랫폼 사본의 보관 기간이 지났거나 삭제됨 | 플랫폼 사본은 복구할 수 없으므로 자신의 아카이브가 있다면 사용 |
텍스트 전용 모델은 assets가 전혀 없으며, output.text의 텍스트도 같은 일정으로 삭제됩니다. 파일이 있다고 가정하기 전에 텍스트를 읽으세요.
저장 실패 시 과금하지 않는 예외는 작업의 어떤 출력도 처음에 저장할 수 없었던 경우에 적용됩니다. 오래된 unavailable 자산만으로는 환불 근거가 되지 않으므로 원래 작업의 정산을 확인하세요.
콜백에는 프롬프트와 서명된 결과 링크가 포함됩니다. 따라서 엔드포인트, 역방향 프록시, 오류 추적 도구, 로그 파이프라인에도 SpicyAPI가 자체 일정에 따라 지우는 자료가 전달됩니다. 접근 로그에서 콜백 본문을 가리고 복사는 워커에서 처리하세요. 서명 검증, 중복 제거, 재시도는 Webhook 문서에 있습니다.
- 제품이 라이브러리, 공유 또는 나중의 편집을 약속한다면: 성공을 확인하는 즉시 자신이 관리하는 비공개 저장소로 결과를 스트리밍하고 자체 자산 ID를 기록하세요. 플랫폼 사본을 없애고 싶다면 그다음 Purge를 호출하세요. 큰 영상을 메모리에 통째로 담는 대신 스트리밍하고, 대상 쓰기가 작업과 자산의 조합에 대해 멱등적이도록 하세요.
- 일회성 전달: 복사하지 마세요. 결과를 보여 주고 유지 기간을 고객에게 알린 뒤 보관 기간이나 짧은
X-Spicy-Retention으로 제거하세요.
사용자가 업로드한 레퍼런스는 마케팅 자산이 아니며, 성공한 결과가 공개 동의를 의미하지도 않습니다. 자신의 사본이 확인된 후에만 “고객이 저장함”으로 표시하세요.
문제가 생겼을 때
| 단계 | 증상 | 올바른 복구 |
|---|---|---|
| 작업 생성 | 응답 유실 | 24시간 중복 제거 기간 안에 저장한 본문을 같은 멱등성 키로 다시 보내고, 기간이 지났을 가능성이 있다면 상태 대조를 위해 중단하세요. 새 키는 두 번째 작업과 요금을 만들 수 있습니다 |
| 콜백 | 중복, 지연 또는 누락 | request_id로 중복을 제거하고 예상한 종료 이벤트가 오지 않으면 recordInfo를 폴링하세요 |
| 결과 복사 | 대기 중인 가져오기나 재연결 전에 링크 만료 | 새 URL을 받아 동일한 대상 키로 다시 스트리밍하세요 |
| 기한 경과 | 410 또는 unavailable | 검증된 아카이브를 먼저 확인하고 저장된 사본이 없다면 이용 불가로 표시하세요 |
창작 자료를 남기지 않으면서 유용한 로그 유지하기
이 경로에 의도하지 않은 사본이 있는지 확인하세요.
- 오류 보고서와 접근 로그: 프롬프트, 티켓, 서명된 링크를 가리고 미디어 경로 본문의 로깅을 피하세요.
- 분석과 큐: URL이나 파일명 대신 내용을 드러내지 않는 작업 처리 ID, 작업 ID, 자산 ID를 사용하세요. 배달 실패 메시지 저장소도 포함됩니다.
- 지원 내보내기와 공개 전달: 스크린샷, 페이지 메타데이터, 이메일을 확인하세요. 접근 권한 확인 후 새 링크를 발급하는 인증된 페이지로 고객을 안내하세요.
- 자신의 저장소와 백업: 자체 삭제 정책을 적용하세요. 만료된 링크로 누군가 이미 다운로드한 파일을 회수할 수는 없습니다.
보관 설정으로 약속할 수 없는 것
- 모델은 프롬프트를 봅니다. 요청을 실행하는 모델은 평문으로 프롬프트를 받으므로 SpicyAPI 설정은 SpicyAPI 자체가 얼마나 오래 보관하는지만 제어합니다. 필요 없는 자료는 보내지 마세요.
- Purge는 비동기 삭제 요청입니다. 반환된 내용 상태와 미디어 삭제 완료를 확인하세요. 저장소 수명 주기 정리와 백업 교체에는 별도의 기간이 있습니다. 직접 복사한 파일과 백업도 각각 삭제 작업이 필요합니다. 과금 기록은 어느 경우에도 남습니다.
계약에 다른 보관 기간을 명시해야 한다면 문서 페이지에서 추론하지 말고 서명 전에 논의하세요.
자주 묻는 질문
임시 업로드 URL을 생성 요청의 이미지 URL로 사용할 수 있나요?
아니요. 업로드 URL은 직접 쓰기만 승인합니다. 업로드하고 확정한 다음 확정된 spicy:// URI를 현재 모델 스키마에서 업로드 필드로 표시한 필드에 넣으세요.
생성된 영상을 SpicyAPI에 14일 넘게 보관할 수 있나요?
API, SDK, Playground 결과는 불가능하며, 상한은 약 14일입니다. Studio 단편 영화 미디어에는 약 60일의 별도 상한이 있습니다. 더 오래 이용하려면 성공 후 파일을 자신의 저장소로 복사하세요.
Purge가 작업 요금을 환불하나요?
아니요. Purge는 내용만 제거하며 요금과 작업 기록은 남습니다.
Webhook이 폴링을 완전히 대체할 수 있나요?
주요 경로가 될 수 있지만 전달 누락을 위한 제한된 대조 확인을 두세요. 처리기는 전달 request_id와 작업 ID를 키로 사용해야 합니다.
결과 링크를 이메일에 넣어도 되나요?
피하세요. 이메일은 단기 링크가 만료된 뒤에도 오래 전달되고 보관됩니다. 접근 권한을 확인하고 새 링크를 발급하는 인증된 페이지로 고객을 안내하세요.
고객이 저장된 결과를 삭제하면 어떻게 해야 하나요?
자신의 사본과 전달 경로를 삭제하거나 무효화하고 처리 기록을 남기세요. 플랫폼 사본은 자체 일정을 따릅니다. 더 빨리 없애야 한다면 Destroy outputs를 사용하세요.
코드로 기존 작업 확인하기
spicyapi를 설치하고 SPICY_API_KEY와 TASK_ID를 설정한 뒤 이 읽기 전용 확인을 실행하세요. 생성 작업을 만들거나 내용을 삭제하지 않습니다.
import json
import os
from spicyapi import SpicyClient
client = SpicyClient()
task = client.get_task(os.environ["TASK_ID"])
print(json.dumps({"taskId": task["taskId"], "state": task["state"],
"contentState": task.get("contentState"), "retention": task.get("retention"),
"mediaDeletionPending": task.get("mediaDeletionPending")}, indent=2))보관 참조 문서에서 요청 설정과 삭제 규약을 설명합니다.
Agent에게 호출 맡기기
이미 작업 ID가 있다면 저장소 확인을 맡기세요. 새 생성은 필요하지 않습니다.
- CLI:
npx @spicyapi/cli tasks get "$TASK_ID"는 현재 기한을 읽습니다. CLI 가이드를 참조하세요. - MCP:
spicyapi_task_get에 해당 작업 검사를 요청하세요.spicyapi_task_purge는 내용 파기를 명시적으로 승인한 후에만 사용하세요. MCP 가이드에서 확인 절차를 설명합니다. - Skill:
npx skills add spicyapi-ai/spicy-skill을 실행한 뒤$spicyapi에 작업의 보관 기간을 검사하고 무엇이 만료되는지 설명해 달라고 요청하세요. Skill 가이드를 참조하세요.
