데이터 보존

개요

모든 비동기 생성은 서로 다른 두 가지를 만들어냅니다:

• 생성된 미디어 — Atlas Cloud가 여러분을 위해 호스팅하고 출력 URL로 반환하는 이미지, 동영상, 오디오 파일입니다.
• 요청 레코드 — 작업의 메타데이터입니다. 모델, 프롬프트와 파라미터, 상태, 타임스탬프, 출력 URL이 포함됩니다. 작업을 폴링할 때 예측 엔드포인트가 읽는 것이 바로 이 레코드입니다.

각각의 보관 기간은 두 개의 헤더로 요청마다 설정할 수 있습니다:

둘 다 선택 사항이며 시간 단위의 정수입니다. 336시간은 14일입니다.

빠른 시작

평소의 제출 요청에 헤더를 함께 보내세요:

curl -X POST https://api.atlascloud.ai/api/v1/model/generateImage \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "X-AtlasCloud-Object-Expiration-Hours: 24" \
  -H "X-AtlasCloud-Request-Retention-Hours: 0" \
  -d '{
        "model": "bytedance/seedream-v5.0-pro/text-to-image",
        "prompt": "A calico kitten chasing a butterfly in a garden"
      }'

import requests

response = requests.post(
    "https://api.atlascloud.ai/api/v1/model/generateImage",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json",
        # 생성된 이미지를 24시간 후에 삭제
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # 작업이 끝나는 즉시 요청 레코드를 삭제
        "X-AtlasCloud-Request-Retention-Hours": "0",
    },
    json={
        "model": "bytedance/seedream-v5.0-pro/text-to-image",
        "prompt": "A calico kitten chasing a butterfly in a garden",
    },
)

print(response.json()["data"]["id"])  # 작업 id(session_id)

const res = await fetch("https://api.atlascloud.ai/api/v1/model/generateImage", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-api-key",
    "Content-Type": "application/json",
    // 생성된 이미지를 24시간 후에 삭제
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // 작업이 끝나는 즉시 요청 레코드를 삭제
    "X-AtlasCloud-Request-Retention-Hours": "0",
  },
  body: JSON.stringify({
    model: "bytedance/seedream-v5.0-pro/text-to-image",
    prompt: "A calico kitten chasing a butterfly in a garden",
  }),
});

const { data } = await res.json();
console.log(data.id); // 작업 id(session_id)

제출 응답은 달라지지 않습니다 — 작업 id를 즉시 돌려받고, 생성도 평소와 완전히 동일하게 진행됩니다. 보존 설정은 작업이 끝난 이후에 무슨 일이 일어날지만 결정합니다.

두 헤더 모두 세 가지 비동기 제출 엔드포인트 전부에서 동작합니다:

• POST /api/v1/model/generateImage
• POST /api/v1/model/generateVideo
• POST /api/v1/model/generateAudio

X-AtlasCloud-Object-Expiration-Hours

이 요청이 생성한 미디어 파일을 Atlas Cloud가 얼마나 오래 저장할지를 작업 제출 시점부터 계산해 설정합니다.

• 범위: 1부터 336시간까지(1시간에서 14일).
• 생략 시 기본값: 14일.
• 최댓값이 기본값과 같기 때문에, 이 헤더는 미디어를 더 빨리 만료시킬 수만 있고 14일을 넘겨 저장 기간을 연장할 수는 없습니다.

미디어가 만료되면 해당 출력 URL은 더 이상 동작하지 않습니다(요청 시 404를 반환합니다). 보관해야 할 것은 그 전에 다운로드하거나 복사해 두세요.

X-AtlasCloud-Request-Retention-Hours

Atlas Cloud가 요청 레코드를 얼마나 오래 보관할지 설정합니다. 이 레코드는 예측 엔드포인트 뒤에 있는 메타데이터 행입니다.

• 범위: 0부터 336시간까지(최대 14일).
• 생략 시 기본값: 레코드는 플랫폼의 표준 보존 정책에 따라 보관됩니다.
• 0은 "생성이 끝나는 즉시 삭제"를 의미합니다 — 작업이 종료 상태(completed, failed, timeout)에 도달한 직후 레코드가 제거됩니다.

레코드가 삭제되고 나면 GET /api/v1/model/prediction/{id}로 해당 작업을 폴링해도 결과 페이로드가 반환되지 않습니다 — 출력물, 파라미터, 오류 상세 정보가 모두 사라집니다. 레코드가 만료되기 전에 필요한 정보를 가져오거나 웹훅을 사용하세요.

값 선택하기

검증

두 헤더는 아무 일도 일어나기 전에 검증됩니다 — 요청이 과금되기 전, 파일이 저장되기 전, 모델 제공자가 호출되기 전입니다. 값이 유효하지 않으면 요청은 HTTP 400으로 거부되며, 작업이 생성되지 않고 과금되지 않습니다.

거부 예시:

{
  "code": 400,
  "msg": "invalid X-AtlasCloud-Object-Expiration-Hours header: 500 is out of range [1, 336]"
}

브라우저에서 API를 호출하는 경우, 두 헤더 이름 모두 CORS 정책에서 허용되므로 교차 출처 요청에서도 전송할 수 있습니다.

비용

사용자 지정 보존 설정은 무료입니다. 기간을 줄이거나 기본값을 유지하더라도 생성 비용은 달라지지 않습니다.

모범 사례

• 보관할 것은 다운로드하세요. Atlas Cloud 스토리지는 아카이브가 아니라 전달용 버퍼로 여기세요 — 특히 객체 만료를 짧게 설정한 경우에 그렇습니다.
• 웹훅을 X-AtlasCloud-Request-Retention-Hours: 0과 함께 사용하세요. 콜백이 작업 완료 순간에 결과를 전달하므로 이후에 레코드가 필요하지 않습니다.
• 레코드 보존은 줄이되 미디어는 유지하는 경우, 출력 URL을 여러분 쪽에 저장하세요.
• 적용하고 싶은 모든 요청에 헤더를 보내세요. 이 헤더는 요청 단위이며, 계정 전체에 적용되는 기본 설정은 없습니다.
• 삭제된 레코드의 URL에 의존하지 마세요. 미디어가 만료되면 그 URL은 404를 반환하므로, 끊어진 링크를 재시도하지 말고 다시 생성하세요.

문제 해결

레퍼런스

• 엔드포인트: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: 정수 1–336, 생성된 미디어에만 적용, 기본값 14일, 단축만 가능.
• X-AtlasCloud-Request-Retention-Hours: 정수 0–336, 요청 레코드에만 적용, 0 = 종료 및 정산 완료 즉시 삭제.
• 잘못된 값: HTTP 400, 작업 생성 없음, 과금 없음.
• 관련 문서: 예측 · 웹훅 · 파일 업로드 · 데이터 삭제 정책