数据保留

用两个相互独立的请求头，按请求控制生成的媒体文件与请求记录的存储时长

概述

每一次异步生成都会产生两样彼此独立的东西：

生成的媒体——由 Atlas Cloud 为你托管、并以输出 URL 形式返回的图像、视频或音频文件。
请求记录——任务的元数据：模型、你的提示词与参数、状态、时间戳以及输出 URL。这正是你轮询任务时预测任务端点所读取的内容。

你可以用两个请求头 按请求 分别设置它们各自的保留时长：

请求头	取值范围	控制对象
`X-AtlasCloud-Object-Expiration-Hours`	`1`–`336`	生成的媒体文件的存储时长。
`X-AtlasCloud-Request-Retention-Hours`	`0`–`336`	请求记录的保留时长。

两者都是可选的整数小时数。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）后不久，记录就会被移除。

记录绝不会在任务进行中被删除

只有在任务确实已经结束，并且其计费与所有 Webhook 投递都已结清之后，记录才会被移除。设置为 0 绝不会中断正在运行的生成任务，也不会让你损失一次回调。

记录被删除后，用 GET /api/v1/model/prediction/{id} 轮询该任务将不再返回结果载荷——输出、参数和错误详情都会消失。请在记录过期前取走你需要的内容（或改用 Webhook）。

删除记录并不会删除媒体。若设置了 X-AtlasCloud-Request-Retention-Hours: 0 而没有设置对象过期请求头，生成的文件仍会在其输出 URL 上完整存活 14 天——只是你必须自己保存好那个 URL，因为 Atlas Cloud 已经没有它的记录了。

取值选择

目标	请求头
任何内容都不保留超过一天	`X-AtlasCloud-Object-Expiration-Hours: 24` + `X-AtlasCloud-Request-Retention-Hours: 24`
尽量少存元数据，但保留文件	`X-AtlasCloud-Request-Retention-Hours: 0`（请自行保存输出 URL）
预览媒体短暂留存，历史记录照常	`X-AtlasCloud-Object-Expiration-Hours: 1`
使用平台默认值	两个请求头都不发送

校验

两个请求头都会在任何操作发生之前完成校验——在请求计费之前、在存储任何文件之前、在调用模型服务商之前。如果取值非法，请求会以 HTTP 400 被拒绝，不会创建任务，也不会计费。

规则	说明
格式	必须是整数小时数。小数（`1.5`）、时长写法（`24h`）以及其他文本都会被拒绝。
`X-AtlasCloud-Object-Expiration-Hours` 取值范围	`1`–`336`。`0` 会被拒绝——最短保留请使用 `1`。
`X-AtlasCloud-Request-Retention-Hours` 取值范围	`0`–`336`。`0` 是合法值，表示「结束后即删除」。
省略或为空	视为「未设置」——采用默认值。

拒绝示例：

{
  "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 使用 Webhook。 回调会在任务结束的瞬间送达结果，因此之后你完全不需要那条记录。
当你缩短记录保留时长但保留媒体时，请 在自己这一侧保存输出 URL。
对每一个需要生效的请求都 带上这些请求头。它们按请求生效；没有账户级的默认设置。
不要依赖已删除记录中的 URL。 媒体一旦过期，其 URL 会返回 404——请重新生成，而不是反复重试失效链接。

故障排查

现象	可能原因 / 处理方式
`400 ... is not a whole number of hours`	取值不是纯整数。请发送 `24`，而不是 `24h` 或 `1.5`。
`400 ... is out of range [1, 336]`	对象过期时间最短 `1` 小时，最长 14 天。
`400 ... is out of range [0, 336]`	请求记录保留时长必须在 `0` 到 14 天之间。
输出 URL 比预期更早返回 `404`	你设置的对象过期时间已到。媒体已被删除；如果仍然需要，请重新生成。
已完成的任务轮询不到输出	请求记录已被你的保留设置删除。请改用 Webhook，或延长保留时长。
记录消失后媒体仍然可用	属于预期行为——两项设置相互独立。文件会一直存活到它自己的过期时间。

参考

端点： 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，不创建任务，不计费。
相关内容： 预测任务 · Webhook · 上传文件 · 数据删除政策

本页目录