数据保留

概述

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

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

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

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

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

取值选择

校验

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

拒绝示例：

{
  "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——请重新生成，而不是反复重试失效链接。

故障排查

参考

• 端点： 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 · 上传文件 · 数据删除政策