Хранение данных

Обзор

Каждая асинхронная генерация создаёт две отдельные сущности:

• Сгенерированный медиафайл — изображение, видео или аудиофайл, который 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"
      }'

Ответ на отправку задачи не меняется — вы сразу получаете 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} больше не возвращает результат — выходные данные, параметры и детали ошибки утрачены. Получите всё необходимое (или используйте вебхук) до истечения срока хранения записи.

Выбор значений

Валидация

Оба заголовка проверяются до того, как что-либо произойдёт: до тарификации запроса, до сохранения файлов и до вызова провайдера модели. Если значение некорректно, запрос отклоняется с 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. Обратный вызов доставляет результат в момент завершения задачи, поэтому запись вам потом не нужна.
• Храните выходной 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, задача не создана, списания нет.
• См. также: Предсказания · Вебхуки · Загрузка файлов · Политика удаления данных