データ保持

概要

非同期生成では、次の 2 つが別々に作成されます:

• 生成されたメディア — Atlas Cloud がホストし、出力 URL として返す画像・動画・音声ファイル。
• リクエスト記録 — タスクのメタデータ。モデル、プロンプトとパラメーター、ステータス、タイムスタンプ、出力 URL などです。タスクをポーリングするときに 予測 エンドポイントが読み取るのがこの記録です。

それぞれの保存期間は、2 つのヘッダーで リクエストごとに 設定できます:

どちらも任意で、時間単位の整数で指定します。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 がすぐに返され、生成も通常どおり実行されます。保持設定が決めるのは、タスクが完了した 後 に何が起きるかだけです。

どちらのヘッダーも、3 つの非同期送信エンドポイントすべてで機能します:

• 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 のストレージはアーカイブではなく配信バッファと考えてください — 特にオブジェクトの有効期限を短くしている場合はなおさらです。
• Webhook を X-AtlasCloud-Request-Retention-Hours: 0 と組み合わせて使う。 タスクが完了した瞬間にコールバックが結果を届けるため、その後に記録が必要になることはありません。
• 記録の保持期間を短くしつつメディアは残す場合は、出力 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 · ファイルアップロード · データ削除ポリシー