Datenaufbewahrung

Überblick

Jede asynchrone Generierung erzeugt zwei getrennte Dinge:

• Generierte Medien — die Bild-, Video- oder Audiodatei, die Atlas Cloud für Sie hostet und als Ausgabe-URL zurückgibt.
• Einen Anfragedatensatz — die Metadaten der Aufgabe: das Modell, Ihr Prompt und Ihre Parameter, der Status, Zeitstempel und die Ausgabe-URLs. Genau diese liest der Vorhersagen-Endpunkt, wenn Sie eine Aufgabe abfragen.

Sie können pro Anfrage festlegen, wie lange beides jeweils aufbewahrt wird — mit zwei Headern:

Beide sind optional und werden als ganze Stundenzahl angegeben. 336 Stunden entsprechen 14 Tagen.

Schnellstart

Senden Sie die Header mit einer normalen Einreichungsanfrage:

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",
        # das generierte Bild nach 24 Stunden löschen
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # den Anfragedatensatz verwerfen, sobald die Aufgabe abgeschlossen ist
        "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"])  # die Aufgaben-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",
    // das generierte Bild nach 24 Stunden löschen
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // den Anfragedatensatz verwerfen, sobald die Aufgabe abgeschlossen ist
    "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); // die Aufgaben-ID (session_id)

Die Antwort auf die Einreichung bleibt unverändert — Sie erhalten sofort eine Aufgaben-id zurück, und die Generierung läuft genau wie gewohnt. Die Aufbewahrung entscheidet nur darüber, was nach dem Abschluss der Aufgabe geschieht.

Beide Header funktionieren an allen drei asynchronen Einreichungs-Endpunkten:

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

X-AtlasCloud-Object-Expiration-Hours

Legt fest, wie lange Atlas Cloud die von dieser Anfrage generierten Mediendateien speichert, gerechnet ab dem Zeitpunkt der Einreichung der Aufgabe.

• Bereich: 1 bis 336 Stunden (1 Stunde bis 14 Tage).
• Standard, wenn nicht gesetzt: 14 Tage.
• Da das Maximum dem Standard entspricht, kann dieser Header Medien immer nur früher ablaufen lassen — er kann die Speicherung nicht über 14 Tage hinaus verlängern.

Sobald die Medien abgelaufen sind, funktionieren ihre Ausgabe-URLs nicht mehr (Anfragen darauf liefern 404). Laden Sie alles, was Sie behalten möchten, vorher herunter oder kopieren Sie es.

X-AtlasCloud-Request-Retention-Hours

Legt fest, wie lange Atlas Cloud den Anfragedatensatz aufbewahrt — die Metadatenzeile hinter dem Vorhersagen-Endpunkt.

• Bereich: 0 bis 336 Stunden (bis zu 14 Tage).
• Standard, wenn nicht gesetzt: Der Datensatz wird gemäß der Standard-Aufbewahrungsrichtlinie der Plattform aufbewahrt.
• 0 bedeutet „löschen, sobald die Generierung fertig ist“ — der Datensatz wird kurz nach Erreichen eines Endzustands der Aufgabe (completed, failed oder timeout) entfernt.

Sobald der Datensatz gelöscht ist, liefert das Abfragen dieser Aufgabe über GET /api/v1/model/prediction/{id} keine Ergebnis-Payload mehr — die Ausgaben, Parameter und Fehlerdetails sind weg. Rufen Sie ab, was Sie benötigen (oder verwenden Sie einen Webhook), bevor der Datensatz abläuft.

Werte auswählen

Validierung

Beide Header werden validiert, bevor irgendetwas geschieht — bevor die Anfrage abgerechnet wird, bevor eine Datei gespeichert wird und bevor der Modellanbieter aufgerufen wird. Ist ein Wert ungültig, wird die Anfrage mit HTTP 400 abgelehnt, es wird keine Aufgabe erstellt, und es entstehen Ihnen keine Kosten.

Beispiel für eine Ablehnung:

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

Wenn Sie die API aus einem Browser aufrufen: Beide Header-Namen sind von der CORS-Richtlinie zugelassen, sodass Cross-Origin-Anfragen sie senden können.

Kosten

Eine individuelle Aufbewahrung ist kostenlos. Ob Sie die Fristen verkürzen oder die Standardwerte beibehalten, ändert nichts an den Kosten einer Generierung.

Best Practices

• Laden Sie herunter, was Sie behalten möchten. Betrachten Sie den Speicher von Atlas Cloud als Zustellpuffer, nicht als Archiv — besonders bei einem kurzen Objektablauf.
• Verwenden Sie Webhooks zusammen mit X-AtlasCloud-Request-Retention-Hours: 0. Der Callback liefert das Ergebnis, sobald die Aufgabe abgeschlossen ist, sodass Sie den Datensatz danach nie brauchen.
• Speichern Sie die Ausgabe-URL auf Ihrer Seite, wenn Sie die Aufbewahrung des Datensatzes verkürzen, die Medien aber behalten.
• Senden Sie die Header bei jeder Anfrage, die davon erfasst werden soll. Sie gelten pro Anfrage; es gibt keine kontoweite Standardeinstellung.
• Verlassen Sie sich nicht auf URLs eines gelöschten Datensatzes. Sobald Medien abgelaufen sind, liefert ihre URL 404 — generieren Sie neu, statt den toten Link erneut aufzurufen.

Fehlerbehebung

Referenz

• Endpunkte: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: Ganzzahl 1–336; nur generierte Medien; Standard 14 Tage; kann nur verkürzen.
• X-AtlasCloud-Request-Retention-Hours: Ganzzahl 0–336; nur Anfragedatensatz; 0 = löschen, sobald Endzustand erreicht und alles abgeschlossen ist.
• Ungültiger Wert: HTTP 400, keine Aufgabe erstellt, keine Kosten.
• Verwandt: Vorhersagen · Webhooks · Dateien hochladen · Datenlöschungsrichtlinie