Retensi Data

Ringkasan

Setiap pembuatan asinkron menghasilkan dua hal yang terpisah:

• Media hasil — file gambar, video, atau audio yang di-host Atlas Cloud untuk Anda dan dikembalikan sebagai URL output.
• Catatan permintaan — metadata tugas: model, prompt dan parameter Anda, status, timestamp, serta URL output. Inilah yang dibaca endpoint Prediksi ketika Anda melakukan polling terhadap sebuah tugas.

Anda dapat mengatur berapa lama masing-masing disimpan, per permintaan, dengan dua header:

Keduanya opsional dan berupa bilangan bulat jam. 336 jam sama dengan 14 hari.

Mulai cepat

Kirim header tersebut bersama permintaan submit biasa:

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",
        # hapus gambar hasil setelah 24 jam
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # buang catatan permintaan begitu tugas selesai
        "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 tugas (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",
    // hapus gambar hasil setelah 24 jam
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // buang catatan permintaan begitu tugas selesai
    "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 tugas (session_id)

Respons submit tidak berubah — Anda langsung menerima id tugas dan pembuatan berjalan persis seperti biasa. Retensi hanya menentukan apa yang terjadi setelah tugas selesai.

Kedua header bekerja pada ketiga endpoint submit asinkron:

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

X-AtlasCloud-Object-Expiration-Hours

Menentukan berapa lama Atlas Cloud menyimpan file media yang dihasilkan permintaan ini, dihitung sejak tugas dikirimkan.

• Rentang: 1 sampai 336 jam (1 jam hingga 14 hari).
• Default bila tidak disertakan: 14 hari.
• Karena nilai maksimumnya sama dengan nilai default, header ini hanya bisa membuat media kedaluwarsa lebih cepat — tidak dapat memperpanjang penyimpanan melebihi 14 hari.

Setelah media kedaluwarsa, URL output-nya berhenti berfungsi (permintaan ke URL tersebut mengembalikan 404). Unduh atau salin apa pun yang perlu Anda simpan sebelum saat itu tiba.

X-AtlasCloud-Request-Retention-Hours

Menentukan berapa lama Atlas Cloud menyimpan catatan permintaan — baris metadata di balik endpoint Prediksi.

• Rentang: 0 sampai 336 jam (hingga 14 hari).
• Default bila tidak disertakan: catatan disimpan mengikuti kebijakan retensi standar platform.
• 0 berarti "hapus segera setelah pembuatan selesai" — catatan dihapus tak lama setelah tugas mencapai status akhir (completed, failed, atau timeout).

Setelah catatan dihapus, polling tugas tersebut dengan GET /api/v1/model/prediction/{id} tidak lagi mengembalikan payload hasil — output, parameter, dan detail error sudah hilang. Ambil apa yang Anda butuhkan (atau gunakan Webhook) sebelum catatan kedaluwarsa.

Memilih nilai

Validasi

Kedua header divalidasi sebelum apa pun terjadi — sebelum permintaan ditagih, sebelum file apa pun disimpan, dan sebelum penyedia model dipanggil. Jika sebuah nilai tidak valid, permintaan ditolak dengan HTTP 400, tidak ada tugas yang dibuat, dan Anda tidak dikenakan biaya.

Contoh penolakan:

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

Jika Anda memanggil API dari browser, kedua nama header ini diizinkan oleh kebijakan CORS, sehingga permintaan lintas-origin dapat mengirimkannya.

Biaya

Retensi kustom gratis. Memperpendek retensi maupun mempertahankan nilai default tidak mengubah biaya sebuah pembuatan.

Praktik terbaik

• Unduh apa yang perlu Anda simpan. Perlakukan penyimpanan Atlas Cloud sebagai buffer pengiriman, bukan arsip — terutama bila masa berlaku object-nya pendek.
• Gunakan Webhook bersama X-AtlasCloud-Request-Retention-Hours: 0. Callback mengirimkan hasil begitu tugas selesai, sehingga Anda tidak lagi membutuhkan catatannya setelah itu.
• Simpan URL output di sisi Anda ketika Anda memperpendek retensi catatan tetapi tetap menyimpan medianya.
• Kirim header pada setiap permintaan yang ingin Anda atur. Header ini berlaku per permintaan; tidak ada pengaturan default untuk seluruh akun.
• Jangan mengandalkan URL dari catatan yang sudah dihapus. Setelah media kedaluwarsa, URL-nya mengembalikan 404 — buat ulang alih-alih mencoba lagi tautan yang sudah mati.

Pemecahan masalah

Referensi

• Endpoint: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: integer 1–336; hanya untuk media hasil; default 14 hari; hanya bisa memperpendek.
• X-AtlasCloud-Request-Retention-Hours: integer 0–336; hanya untuk catatan permintaan; 0 = hapus setelah mencapai status akhir dan tuntas.
• Nilai tidak valid: HTTP 400, tidak ada tugas yang dibuat, tidak ada biaya.
• Terkait: Prediksi · Webhook · Upload File · Kebijakan Penghapusan Data