資料保留

逐次請求控制生成媒體與請求紀錄的保存時間——由兩個各自獨立的標頭決定

概覽

每一次非同步生成都會產生兩樣各自獨立的東西：

生成的媒體——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 的儲存視為傳遞用的緩衝，而非封存空間——尤其是在物件到期時間設得很短時。
搭配 Webhook 使用 X-AtlasCloud-Request-Retention-Hours: 0。 任務一結束回呼就會送出結果，因此之後您根本不需要那筆紀錄。
當您縮短紀錄保留時間但要保留媒體時，請在自己這端保存輸出 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 · 上傳檔案 · 資料刪除政策

本頁目錄