Data Retention

Overview

Every async generation creates two separate things:

• Generated media — the image, video, or audio file Atlas Cloud hosts for you and returns as an output URL.
• A request record — the task's metadata: the model, your prompt and parameters, the status, timestamps, and the output URLs. This is what the Predictions endpoint reads when you poll a task.

You can set how long each one is kept, per request, with two headers:

Both are optional whole numbers of hours. 336 hours is 14 days.

Quick start

Send the headers with a normal submit request:

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",
        # delete the generated image after 24 hours
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # drop the request record as soon as the task finishes
        "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"])  # the task 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",
    // delete the generated image after 24 hours
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // drop the request record as soon as the task finishes
    "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); // the task id (session_id)

The submit response is unchanged — you get a task id back immediately and the generation runs exactly as it normally would. Retention only decides what happens after the task finishes.

Both headers work on all three async submit endpoints:

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

X-AtlasCloud-Object-Expiration-Hours

Sets how long Atlas Cloud stores the media files this request generates, counted from the moment the task is submitted.

• Range: 1 to 336 hours (1 hour to 14 days).
• Default when omitted: 14 days.
• Because the maximum equals the default, this header can only ever make media expire sooner — it cannot extend storage beyond 14 days.

Once the media expires, its output URLs stop working (requests to them return 404). Download or copy anything you need to keep before then.

X-AtlasCloud-Request-Retention-Hours

Sets how long Atlas Cloud keeps the request record — the metadata row behind the Predictions endpoint.

• Range: 0 to 336 hours (up to 14 days).
• Default when omitted: the record is kept under the platform's standard retention policy.
• 0 means "delete as soon as the generation is done" — the record is removed shortly after the task reaches a terminal state (completed, failed, or timeout).

Once the record is deleted, polling that task with GET /api/v1/model/prediction/{id} no longer returns the result payload — the outputs, parameters, and error details are gone. Retrieve what you need (or use a webhook) before the record expires.

Choosing values

Validation

Both headers are validated before anything happens — before the request is billed, before any file is stored, and before the model provider is called. If a value is invalid, the request is rejected with HTTP 400, no task is created, and you are not charged.

Example rejection:

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

If you call the API from a browser, both header names are allowed by the CORS policy, so cross-origin requests can send them.

Cost

Custom retention is free. Shortening or keeping the defaults does not change what a generation costs.

Best practices

• Download what you need to keep. Treat Atlas Cloud storage as a delivery buffer, not an archive — especially with a short object expiration.
• Use webhooks with X-AtlasCloud-Request-Retention-Hours: 0. The callback delivers the result the moment the task finishes, so you never need the record afterwards.
• Store the output URL on your side when you shorten record retention but keep the media.
• Send the headers on every request you want covered. They are per-request; there is no account-wide default setting.
• Don't rely on a deleted record's URLs. Once media expires, its URL returns 404 — re-generate rather than retrying the dead link.

Troubleshooting

Reference

• Endpoints: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: integer 1–336; generated media only; default 14 days; can only shorten.
• X-AtlasCloud-Request-Retention-Hours: integer 0–336; request record only; 0 = delete once terminal and settled.
• Invalid value: HTTP 400, no task created, no charge.
• Related: Predictions · Webhooks · Upload files · Data deletion policy