Conservazione dei dati

Panoramica

Ogni generazione asincrona crea due elementi distinti:

• Media generati — il file di immagine, video o audio che Atlas Cloud ospita per te e restituisce come URL di output.
• Un record della richiesta — i metadati dell'attività: il modello, il tuo prompt e i parametri, lo stato, i timestamp e gli URL di output. È ciò che l'endpoint Predizioni legge quando interroghi un'attività.

Puoi impostare per quanto tempo ciascuno viene conservato, per singola richiesta, con due header:

Entrambi sono numeri interi di ore opzionali. 336 ore corrispondono a 14 giorni.

Avvio rapido

Invia gli header con una normale richiesta di invio:

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",
        # elimina l'immagine generata dopo 24 ore
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # elimina il record della richiesta non appena l'attività termina
        "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"])  # l'id dell'attività (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",
    // elimina l'immagine generata dopo 24 ore
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // elimina il record della richiesta non appena l'attività termina
    "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); // l'id dell'attività (session_id)

La risposta di invio è invariata — ricevi subito un id dell'attività e la generazione procede esattamente come al solito. La conservazione decide solo cosa accade dopo il termine dell'attività.

Entrambi gli header funzionano su tutti e tre gli endpoint di invio asincrono:

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

X-AtlasCloud-Object-Expiration-Hours

Imposta per quanto tempo Atlas Cloud archivia i file multimediali generati da questa richiesta, a partire dal momento in cui l'attività viene inviata.

• Intervallo: da 1 a 336 ore (da 1 ora a 14 giorni).
• Valore predefinito se omesso: 14 giorni.
• Poiché il massimo coincide con il valore predefinito, questo header può solo far scadere i media prima — non può estendere l'archiviazione oltre i 14 giorni.

Una volta scaduti i media, i loro URL di output smettono di funzionare (le richieste restituiscono 404). Scarica o copia tutto ciò che vuoi conservare prima di quel momento.

X-AtlasCloud-Request-Retention-Hours

Imposta per quanto tempo Atlas Cloud conserva il record della richiesta — la riga di metadati dietro l'endpoint Predizioni.

• Intervallo: da 0 a 336 ore (fino a 14 giorni).
• Valore predefinito se omesso: il record viene conservato secondo la politica di conservazione standard della piattaforma.
• 0 significa "elimina non appena la generazione è conclusa" — il record viene rimosso poco dopo che l'attività raggiunge uno stato terminale (completed, failed o timeout).

Una volta eliminato il record, interrogare quell'attività con GET /api/v1/model/prediction/{id} non restituisce più il payload del risultato — output, parametri e dettagli degli errori non ci sono più. Recupera ciò che ti serve (o usa un webhook) prima che il record scada.

Scelta dei valori

Validazione

Entrambi gli header vengono validati prima che accada qualsiasi cosa — prima che la richiesta venga addebitata, prima che qualsiasi file venga archiviato e prima che il provider del modello venga chiamato. Se un valore non è valido, la richiesta viene rifiutata con HTTP 400, nessuna attività viene creata e non ti viene addebitato nulla.

Esempio di rifiuto:

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

Se chiami l'API da un browser, entrambi i nomi degli header sono consentiti dalla politica CORS, quindi le richieste cross-origin possono inviarli.

Costo

La conservazione personalizzata è gratuita. Accorciarla o mantenere i valori predefiniti non modifica il costo di una generazione.

Buone pratiche

• Scarica ciò che vuoi conservare. Considera l'archiviazione di Atlas Cloud come un buffer di consegna, non come un archivio — soprattutto con una scadenza degli oggetti breve.
• Usa i webhook con X-AtlasCloud-Request-Retention-Hours: 0. Il callback consegna il risultato nel momento in cui l'attività termina, quindi non hai più bisogno del record.
• Conserva l'URL di output dalla tua parte quando accorci la conservazione del record ma mantieni i media.
• Invia gli header su ogni richiesta che vuoi coprire. Sono per singola richiesta; non esiste un'impostazione predefinita a livello di account.
• Non fare affidamento sugli URL di un record eliminato. Una volta scaduti i media, il loro URL restituisce 404 — rigenera invece di riprovare con il link ormai inattivo.

Risoluzione dei problemi

Riferimento

• Endpoint: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: intero 1–336; solo media generati; valore predefinito 14 giorni; può solo accorciare.
• X-AtlasCloud-Request-Retention-Hours: intero 0–336; solo record della richiesta; 0 = elimina una volta terminato e finalizzato.
• Valore non valido: HTTP 400, nessuna attività creata, nessun addebito.
• Correlati: Predizioni · Webhook · Carica file · Politica di cancellazione dei dati