Retenção de dados

Visão geral

Toda geração assíncrona cria duas coisas separadas:

• A mídia gerada — o arquivo de imagem, vídeo ou áudio que o Atlas Cloud hospeda para você e retorna como URL de saída.
• Um registro da solicitação — os metadados da tarefa: o modelo, seu prompt e parâmetros, o status, os carimbos de tempo e as URLs de saída. É isso que o endpoint de Predições lê quando você consulta uma tarefa.

Você pode definir por quanto tempo cada um deles é mantido, por solicitação, com dois cabeçalhos:

Ambos são opcionais e recebem números inteiros de horas. 336 horas equivalem a 14 dias.

Início rápido

Envie os cabeçalhos junto com uma solicitação de envio 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"
      }'

A resposta ao envio não muda — você recebe de imediato um id de tarefa e a geração roda exatamente como de costume. A retenção só decide o que acontece depois que a tarefa termina.

Ambos os cabeçalhos funcionam nos três endpoints de envio assíncrono:

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

X-AtlasCloud-Object-Expiration-Hours

Define por quanto tempo o Atlas Cloud armazena os arquivos de mídia que esta solicitação gera, contados a partir do momento em que a tarefa é enviada.

• Intervalo: 1 a 336 horas (de 1 hora a 14 dias).
• Padrão quando omitido: 14 dias.
• Como o máximo é igual ao padrão, este cabeçalho só pode fazer a mídia expirar mais cedo — ele não estende o armazenamento além de 14 dias.

Assim que a mídia expira, suas URLs de saída deixam de funcionar (solicitações a elas retornam 404). Baixe ou copie tudo o que você precisa manter antes disso.

X-AtlasCloud-Request-Retention-Hours

Define por quanto tempo o Atlas Cloud mantém o registro da solicitação — a linha de metadados por trás do endpoint de Predições.

• Intervalo: 0 a 336 horas (até 14 dias).
• Padrão quando omitido: o registro é mantido conforme a política de retenção padrão da plataforma.
• 0 significa "excluir assim que a geração terminar" — o registro é removido logo depois que a tarefa atinge um estado terminal (completed, failed ou timeout).

Depois que o registro é excluído, consultar essa tarefa com GET /api/v1/model/prediction/{id} deixa de retornar o payload do resultado — as saídas, os parâmetros e os detalhes do erro desaparecem. Obtenha o que você precisa (ou use um webhook) antes que o registro expire.

Como escolher os valores

Validação

Ambos os cabeçalhos são validados antes de qualquer coisa acontecer — antes de a solicitação ser cobrada, antes de qualquer arquivo ser armazenado e antes de o provedor do modelo ser chamado. Se um valor for inválido, a solicitação é rejeitada com HTTP 400, nenhuma tarefa é criada e você não é cobrado.

Exemplo de rejeição:

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

Se você chamar a API a partir de um navegador, ambos os nomes de cabeçalho são permitidos pela política de CORS, então solicitações de origem cruzada podem enviá-los.

Custo

A retenção personalizada é gratuita. Encurtá-la ou manter os padrões não altera o custo de uma geração.

Boas práticas

• Baixe o que você precisa manter. Trate o armazenamento do Atlas Cloud como um buffer de entrega, e não como um arquivo permanente — especialmente com uma expiração de objeto curta.
• Use webhooks com X-AtlasCloud-Request-Retention-Hours: 0. O callback entrega o resultado no instante em que a tarefa termina, então você nunca precisa do registro depois disso.
• Guarde a URL de saída do seu lado quando você encurtar a retenção do registro, mas mantiver a mídia.
• Envie os cabeçalhos em toda solicitação que você quiser cobrir. Eles são por solicitação; não existe uma configuração padrão para a conta inteira.
• Não conte com as URLs de um registro excluído. Assim que a mídia expira, sua URL retorna 404 — gere novamente em vez de insistir no link morto.

Solução de problemas

Referência

• Endpoints: POST /api/v1/model/generateImage, POST /api/v1/model/generateVideo, POST /api/v1/model/generateAudio.
• X-AtlasCloud-Object-Expiration-Hours: inteiro 1–336; apenas a mídia gerada; padrão de 14 dias; só pode encurtar.
• X-AtlasCloud-Request-Retention-Hours: inteiro 0–336; apenas o registro da solicitação; 0 = excluir assim que estiver terminal e concluído.
• Valor inválido: HTTP 400, nenhuma tarefa criada, nenhuma cobrança.
• Relacionado: Predições · Webhooks · Enviar arquivos · Política de exclusão de dados