Retenção e destruição

A retenção tem duas camadas. O limite da plataforma é um compromisso público, não um ajuste interno. Dentro dele, você pode definir prazos próprios mais curtos e destruir o conteúdo de uma tarefa quando quiser.

A relação entre as camadas cabe em uma frase: você só pode reduzir o prazo; nenhuma configuração sua aumenta o limite.

Por quanto tempo guardamos os dados: limites da plataforma

Você pode reduzir os prazos das primeiras quatro linhas com os quatro controles abaixo: resultados gerados, incluindo mídia e dados de resultado, mídia de curtas, texto do prompt e arquivos enviados.

A mídia de curtas tem prazo maior porque um filme no Spicy Studio é construído ao longo de dias ou semanas, e uma cena criada na primeira semana ainda precisa existir quando o filme inteiro for exportado. Isso só vale para tarefas iniciadas em um projeto de curta no Studio; o mesmo modelo chamado pela API, por um SDK ou pelo Playground mantém o limite de 14 dias, e o texto do prompt mantém o limite de 30 dias em ambos os casos. Os demais prazos são obrigações da plataforma ou legais e não mudam com suas configurações.

Quatro prazos, configurados separadamente

Eles respondem a quatro perguntas diferentes, não à mesma pergunta com quatro ajustes. Os nomes abaixo são os exibidos no console:

Configure-os em Retenção, na página Proteção de dados do console. Quando uma tarefa é aceita, recebe prazos próprios de expiração de resultado e prompt conforme essas configurações e o cabeçalho abaixo; você pode consultá-los em retention de recordInfo.

“Excluir ao concluir a tarefa” significa que um arquivo enviado é excluído quando todas as tarefas que o usam chegam a um estado final (succeeded / failed / canceled / expired), normalmente em até um minuto; não na criação da tarefa, pois uma nova tentativa precisa dele. Entenda a consequência antes: executar novamente a mesma imagem exige outro upload, e uma nova tentativa falhará.

Efeito de uma alteração sobre conteúdo existente

Alterar um prazo não é simplesmente mudar o comportamento “daqui em diante”. Algumas mudanças afetam tarefas que você já executou; outras não. Hoje funciona assim:

Algumas mudanças alcançam o passado porque, embora os prazos de cada tarefa sejam fixados na aceitação, uma segunda limpeza trabalha com dias inteiros. Ela usa a configuração de Texto do prompt, arredonda para cima para 1, 7 ou 30 dias e a aplica a todas as tarefas encerradas da conta. Ao limpar uma tarefa, limpa o texto do prompt e os resultados juntos.

A mesma página tem um segundo cartão, Retenção de conteúdo de tarefas, que controla diretamente essa limpeza por dias:

• Escolher 1 dia ou 7 dias limpa texto do prompt, resultados e arquivos gerados de todas as tarefas concluídas há mais tempo que o escolhido, e continua fazendo isso à medida que cada tarefa atinge essa idade.
• Ativar Limpar conteúdo logo após a conclusão limpa esses dados de todas as tarefas encerradas, incluindo as executadas antes da ativação, cerca de uma hora após a conclusão de cada uma.
• Os dois cartões compartilham configurações: salvar em um altera o valor exibido no outro.

Ajuste por solicitação: X-Spicy-Retention

Quando você não quer alterar a configuração da conta, mas deseja que apenas esta geração seja removida mais cedo, envie o cabeçalho na criação da tarefa. O valor é um inteiro em segundos e se aplica aos arquivos e ao prompt desta tarefa:

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "X-Spicy-Retention: 3600" \
  --data "$TASK_PAYLOAD"

• Só pode reduzir. O valor efetivo é min(header, account setting, platform cap). Depois que um administrador define a conta em uma hora, uma solicitação não pode recuperar 14 dias; caso contrário, a configuração seria apenas uma sugestão.
• 0 é válido e significa “excluir os arquivos assim que a tarefa atingir um estado final”.
• Um valor inválido não faz a solicitação falhar. Um número negativo é ajustado para 0; um valor acima do limite é reduzido ao limite; um valor que não seja um inteiro decimal é ignorado, aplicando-se a configuração da conta. O valor efetivamente aplicado sempre é informado em retention de recordInfo. Um cabeçalho que só pede mais cautela nunca deve impedir uma geração.
• Endpoints que o leem. jobs/createTask e jobs/stream o leem. jobs/retry herda o valor efetivo da tarefa original e ignora o cabeçalho: uma nova tentativa repete o mesmo trabalho, e escolher outro prazo daria duas expirações a uma mesma família de tarefas. jobs/quote não o lê porque não cria tarefa.

recordInfo retorna retention para cada tarefa; a própria resposta de createTask não o inclui, portanto consulte depois que a tarefa existir:

{
  "retention": {
    "outputsExpireAt": "2026-09-13T12:00:00Z",
    "promptsExpireAt": "2026-09-13T12:00:00Z",
    "source": "header"
  }
}

source indica a camada determinante: header, esta solicitação; account, a configuração da conta; ou platform, o limite. Enviar o cabeçalho e ainda receber account significa que a configuração da conta já era menor que o prazo pedido.

Antes do término, outputsExpireAt é medido a partir da aceitação; quando a tarefa chega a um estado final, a referência passa para a conclusão, usando o mesmo intervalo. Portanto, o horário só se move para mais tarde, nunca para antes. Confie nos horários da resposta, em vez de recalculá-los: o resultado dos três limites nem sempre é o esperado. Além da destruição solicitada por você, só uma configuração da conta que alcance tarefas anteriores pode remover conteúdo antes desses horários, conforme explicado acima.

Destruir conteúdo sob demanda: POST /jobs/purge

Quando você não quer esperar a expiração:

• No console, abra a tarefa em Logs e escolha Destruir saídas, a mesma ação do endpoint abaixo.
• Remover do histórico, na mesma tarefa, também limpa prompt e resultado, agenda a exclusão da mídia e, além disso, oculta a tarefa dos seus logs. A ação fica disponível depois do encerramento da tarefa e da liquidação do faturamento.

Nenhuma das ações muda a cobrança nem cancela uma tarefa. Por código:

curl -X POST https://api.spicyapi.ai/api/v1/jobs/purge \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"taskId": "job_01k..."}'

A resposta:

{
  "taskId": "job_01k...",
  "contentState": "purged",
  "purgedAt": "2026-09-13T12:00:00Z",
  "contentRemovedBy": "user",
  "billingRetained": true,
  "mediaDeletionPending": true
}

Algumas regras:

• Somente tarefas em estado final (succeeded / failed / canceled / expired). Espere a tarefa em execução terminar: os arquivos ainda não chegaram, e uma exclusão pela metade é pior que não excluir. Uma tarefa de geração não pode ser cancelada após a aceitação; não existe um caminho de “cancelar primeiro, destruir depois”.
• Idempotente e sem necessidade de Idempotency-Key. O endpoint é idempotente por taskId: chamá-lo de novo para uma tarefa já destruída ainda retorna 200, e purgedAt é o horário da primeira destruição, não desta chamada. Repetir após um tempo limite é seguro.
• A resposta significa “agendado”, não “já excluído”. Enquanto mediaDeletionPending for verdadeiro, contentState já é purged, mas a limpeza em segundo plano ainda não terminou de remover os objetos; normalmente termina em até um minuto. Excluir de forma síncrona permitiria que um único objeto problemático bloqueasse toda a solicitação, justamente quando você precisa de uma resposta clara.
• Uma resposta ainda em present significa que esta chamada não removeu nada, por exemplo porque a tarefa está sob obrigação de preservação. Você pode tentar depois; o motivo específico não é divulgado intencionalmente.
• billingRetained sempre é true. Parece redundante, mas está ali porque é a informação que o usuário mais provavelmente interpretaria de forma errada nesse endpoint; veja abaixo.

contentState: existência do conteúdo e responsável pela remoção

Os detalhes da tarefa têm um contentState com três valores:

Os dois últimos incluem purgedAt, quando o conteúdo foi removido, e contentRemovedBy, com system para a limpeza e user para você.

Exibir purged como “expirado” erra pelo mesmo motivo, no sentido inverso: um caso decorre de um botão pressionado pelo usuário; o outro, da execução programada da nossa política. Inverter a explicação faz as pessoas concluírem que a plataforma perdeu seus arquivos.

A expiração limpa campos, não registros

A limpeza abrange input, output, URLs de callback e o conteúdo relacionado de eventos e callbacks. O próprio registro da tarefa é mantido por prazo indeterminado: é a única evidência em uma disputa de faturamento, e apagá-lo quebraria a contabilidade. Depois, cada registro contém algumas centenas de bytes de metadados: ID da tarefa, modelo, estado, valor, horários e chave de origem. A destruição sob demanda segue a mesma regra; só o momento é escolhido por você.

Depois que o conteúdo é removido:

• Você ainda pode responder “quanto fui cobrado neste mês, quais tarefas falharam e qual chave as enviou”.
• Você não pode responder “qual prompt enviei e qual chave de objeto guardava o arquivo”: recordInfo deixa de retornar input e output a partir daí.

Se precisar de prompts por mais tempo, mantenha uma cópia própria. Uma obrigação ativa de preservação suspende a exclusão correspondente e também bloqueia a destruição sob demanda; nenhuma das duas pode restaurar uma saída já excluída fisicamente.

Histórico de saldo é separado do conteúdo das tarefas

Limpar input e output de uma tarefa, por expiração ou por destruição solicitada, não altera recargas, reservas, liquidações, reservas devolvidas nem ajustes manuais. Você ainda pode conciliar essas movimentações na página de faturamento do console. Registros do histórico financeiro seguem uma retenção de dez anos e não são removidos quando o conteúdo de uma tarefa expira ou é destruído.

Se uma solicitação de acesso ou exclusão abranger dados que precisam ser mantidos por disputa, investigação de segurança ou legislação aplicável, nossa resposta explicará o escopo e o motivo.

Duas coisas que não podemos fazer

A exceção: obrigações legais de preservação

Tarefas envolvidas em disputas, solicitações periciais ou obrigações legais de denúncia são colocadas sob preservação e param de contar o prazo até sua liberação. A destruição sob demanda não ocorre enquanto a preservação estiver em vigor.

Isso prevalece sobre todos os números e configurações acima. Não é uma exceção reservada em silêncio: sem um mecanismo de preservação, a primeira notificação legal obrigaria a descumprir uma promessa de retenção, e você teria de explicar por que a documentação dizia 14 dias. Essa informação está aqui porque faz parte do assunto.

O que está nas suas mãos

• Defina cada prazo conforme sua necessidade real. São separados: não altere uploads para “Excluir ao concluir a tarefa” como consequência indireta de querer prompts por menos tempo.
• Baixe antes de reduzir. Um prazo menor pode alcançar tarefas já executadas; veja efeitos de uma alteração.
• Use X-Spicy-Retention em solicitações sensíveis pontuais. Não é necessário reconfigurar a conta inteira para uma geração.
• Não envie o que não precisa enviar. Imagens de referência e prompts são os dois itens mais sensíveis e os únicos cujo conteúdo você escolhe.
• Arquive seus próprios arquivos gerados. Eles duram no máximo cerca de 14 dias, ou 60 dias para mídia de curtas, e menos se você reduzir o prazo.
• Guarde uma cópia dos dados da conta. Baixar seus dados, na página Proteção de dados, fornece um JSON com perfil, papéis em equipes, detalhes de chaves de API, nunca os segredos, dados de tarefas ainda retidos e registros financeiros. Não inclui arquivos de mídia; baixe separadamente os resultados necessários.
• Não armazene URLs de download no banco de dados. Elas expiram em 20 minutos e não podem ser revogadas após a emissão. Assine uma quando precisar; veja Mídia.
• Use HTTPS nas URLs de callback. O conteúdo inclui estado da tarefa e referências de arquivos; HTTP simples os expõe a qualquer pessoa no caminho.

Não treinamos com seu conteúdo

Seus prompts, imagens de referência e arquivos gerados não entram em nenhum conjunto de treinamento.

O limite dessa frase importa: ela se refere a nós. Não somos nós que definimos as políticas de cada modelo; veja o primeiro ponto acima.