Retención de datos

Descripción general

Cada generación asíncrona crea dos cosas distintas:

• Archivos multimedia generados — el archivo de imagen, video o audio que Atlas Cloud aloja por ti y devuelve como URL de salida.
• Un registro de solicitud — los metadatos de la tarea: el modelo, tu prompt y parámetros, el estado, las marcas de tiempo y las URLs de salida. Esto es lo que lee el endpoint de Predicciones cuando consultas una tarea.

Puedes definir cuánto tiempo se conserva cada uno, por solicitud, con dos encabezados:

Ambos son opcionales y se expresan en horas enteras. 336 horas son 14 días.

Inicio rápido

Envía los encabezados con una solicitud de envío normal:

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",
        # elimina la imagen generada después de 24 horas
        "X-AtlasCloud-Object-Expiration-Hours": "24",
        # descarta el registro de solicitud en cuanto termine la tarea
        "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"])  # el id de la tarea (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",
    // elimina la imagen generada después de 24 horas
    "X-AtlasCloud-Object-Expiration-Hours": "24",
    // descarta el registro de solicitud en cuanto termine la tarea
    "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); // el id de la tarea (session_id)

La respuesta al envío no cambia — recibes de inmediato un id de tarea y la generación se ejecuta exactamente como lo haría normalmente. La retención solo decide qué ocurre después de que la tarea termina.

Ambos encabezados funcionan en los tres endpoints de envío asíncrono:

• POST /api/v1/model/generateImage
• POST /api/v1/model/generateVideo
• POST /api/v1/model/generateAudio

X-AtlasCloud-Object-Expiration-Hours

Define cuánto tiempo almacena Atlas Cloud los archivos multimedia que genera esta solicitud, contando desde el momento en que se envía la tarea.

• Rango: de 1 a 336 horas (de 1 hora a 14 días).
• Valor por defecto si se omite: 14 días.
• Como el máximo coincide con el valor por defecto, este encabezado solo puede hacer que los archivos multimedia expiren antes — no puede extender el almacenamiento más allá de 14 días.

Una vez que los archivos multimedia expiran, sus URLs de salida dejan de funcionar (las solicitudes a ellas devuelven 404). Descarga o copia todo lo que necesites conservar antes de ese momento.

X-AtlasCloud-Request-Retention-Hours

Define cuánto tiempo conserva Atlas Cloud el registro de solicitud — la fila de metadatos que hay detrás del endpoint de Predicciones.

• Rango: de 0 a 336 horas (hasta 14 días).
• Valor por defecto si se omite: el registro se conserva según la política de retención estándar de la plataforma.
• 0 significa "eliminar en cuanto la generación termine" — el registro se elimina poco después de que la tarea alcance un estado terminal (completed, failed o timeout).

Una vez eliminado el registro, consultar esa tarea con GET /api/v1/model/prediction/{id} ya no devuelve la carga útil del resultado — las salidas, los parámetros y los detalles del error desaparecen. Recupera lo que necesites (o usa un webhook) antes de que el registro expire.

Elegir valores

Validación

Ambos encabezados se validan antes de que ocurra nada — antes de que se facture la solicitud, antes de que se almacene ningún archivo y antes de que se llame al proveedor del modelo. Si un valor no es válido, la solicitud se rechaza con HTTP 400, no se crea ninguna tarea y no se te cobra.

Ejemplo de rechazo:

{
  "code": 400,
  "msg": "invalid X-AtlasCloud-Object-Expiration-Hours header: 500 is out of range [1, 336]"
}

Si llamas a la API desde un navegador, ambos nombres de encabezado están permitidos por la política CORS, por lo que las solicitudes de origen cruzado pueden enviarlos.

Coste

La retención personalizada es gratuita. Acortarla o mantener los valores por defecto no cambia lo que cuesta una generación.

Mejores prácticas

• Descarga lo que necesites conservar. Trata el almacenamiento de Atlas Cloud como un búfer de entrega, no como un archivo histórico — especialmente con una expiración de objeto corta.
• Usa webhooks con X-AtlasCloud-Request-Retention-Hours: 0. El callback entrega el resultado en el momento en que la tarea termina, así que después nunca necesitas el registro.
• Guarda la URL de salida de tu lado cuando acortes la retención del registro pero conserves los archivos multimedia.
• Envía los encabezados en cada solicitud que quieras cubrir. Son por solicitud; no existe un ajuste por defecto para toda la cuenta.
• No dependas de las URLs de un registro eliminado. Una vez que los archivos multimedia expiran, su URL devuelve 404 — vuelve a generar en lugar de reintentar el enlace muerto.

Solución de problemas

Referencia

• Endpoints: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: entero 1–336; solo archivos multimedia generados; por defecto 14 días; solo puede acortar.
• X-AtlasCloud-Request-Retention-Hours: entero 0–336; solo el registro de solicitud; 0 = eliminar una vez terminado y liquidado.
• Valor no válido: HTTP 400, no se crea ninguna tarea, sin cargo.
• Relacionado: Predicciones · Webhooks · Subir archivos · Política de eliminación de datos