Mídia de IA: URLs temporárias de upload, resultados de curta duração e entrega confiável por API

Se você está criando um produto de imagens ou vídeos de IA sem censura, três fatos determinam seu projeto de armazenamento. Arquivos de referência enviados duram 1 dia. Mídias geradas por tarefas de API, SDK e Playground duram cerca de 14 dias (mídias de curtas-metragens do Studio têm um limite separado de cerca de 60 dias), e cada link de download recebido funciona por apenas cerca de 20 minutos. Todos são limites máximos: você só pode reduzi-los, para a conta inteira ou para uma solicitação, e destruir o conteúdo de uma tarefa concluída sob demanda. Nenhuma configuração aumenta esses limites.

Assim, o fluxo confiável é: enviar diretamente com um ticket de curta duração, confirmar o arquivo, submeter uma tarefa assíncrona com a referência privada spicy://, obter o link do resultado quando a tarefa terminar e copiar o resultado para um armazenamento sob seu controle ou deixá-lo expirar de propósito. Não coloque o upload de um cliente em um bucket público nem salve uma URL de download retornada como se fosse permanente.

Enviar uma referência para o SpicyAPI é grátis; a tarefa de geração que a utiliza é cobrada separadamente. Renovar o link de download de um resultado existente não executa nem compra a geração novamente. Uma nova tentativa de geração tem sua própria cobrança do modelo, enquanto armazenamento, solicitações e transferência da cópia no seu bucket seguem os preços do seu provedor de armazenamento.

Leia os prazos de retenção aceitos antes de prometer um período de armazenamento aos clientes; a documentação de retenção explica as configurações. Um exemplo prático de cópia local está em transformar mídias temporárias de IA em recursos duradouros do produto.

Experimente primeiro no Playground

1. Abra a página de texto para imagem do z-image, permaneça em Workbench, em Form, digite um Prompt, escolha um Aspect ratio e selecione Run model (faça login primeiro; essa imagem é uma geração normal paga). Confira em Preview e salve com Download.
2. No Console, abra Logs e encontre essa tarefa para ver por quanto tempo sua saída é mantida.
3. Abra Data protection e depois Retention para ver os quatro prazos e reduzir qualquer um deles.
4. Depois de ter sua própria cópia, selecione Destroy outputs na tarefa concluída para excluir seu conteúdo.

O que o SpicyAPI mantém e por quanto tempo

Reduza a retenção ou destrua o conteúdo você mesmo

1. Prazos de retenção da conta. Em Retention, na página Data protection do console, há quatro prazos separados:

O prazo dos arquivos enviados tem três limites importantes:

• Delete when the job ends: um upload é removido quando todas as tarefas que o utilizam chegam a um estado final, normalmente em um minuto. Uma nova geração usando essa referência excluída precisa de outro upload.
• Somente arquivos existentes: essa opção se aplica aos arquivos presentes quando você salva. Uploads posteriores atualmente mantêm a expiração padrão de 1 dia mostrada na resposta de confirmação.
• Opções de 1 hora e 24 horas: atualmente não mudam nada; o upload continua utilizável até o expiresAt retornado.

Aviso antes de reduzir qualquer prazo: uma configuração mais curta pode alcançar tarefas já executadas. Definir Prompt text para 1 ou 24 horas, por exemplo, apaga o texto do prompt e os resultados gerados de todas as tarefas concluídas há mais de um dia, mesmo que Generated results continue em 14 dias. Conteúdo excluído não pode ser restaurado. Baixe primeiro o que quiser manter; ampliar uma configuração só afeta o futuro.

2. Uma solicitação por vez. Envie o cabeçalho X-Spicy-Retention (segundos) ao criar uma tarefa; a documentação de retenção mostra a solicitação. O período efetivo é o menor entre o da solicitação, a configuração da conta e o limite da plataforma. Leia os prazos aceitos na tarefa em vez de prometer a duração solicitada.

Não use exclusão imediata em um produto que prometa entrega ou uma biblioteca salva. Ela pode remover o resultado antes que sua cópia termine. Deixe uma margem de recuperação após a entrega.

3. Destruir uma tarefa concluída. Depois de copiar o que precisa, ou quando um cliente solicitar exclusão, remova o conteúdo criativo dessa tarefa.

O console oferece a mesma ação como Destroy outputs em uma tarefa em Logs. Três regras se aplicam:

• Somente tarefas concluídas. Purge é idempotente por taskId; não precisa de Idempotency-Key. Não cancela a geração nem reembolsa a cobrança, e billingRetained permanece true.
• A exclusão é agendada. contentState passa a purged enquanto mediaDeletionPending permanece true até a limpeza terminar, normalmente em um minuto. Confirme a conclusão antes de dizer ao cliente que os bytes foram removidos.
• Uma resposta present não removeu nada. Investigue a resposta e as configurações de preservação em vez de informar que a exclusão terminou.

contentState é expired quando o prazo de retenção removeu o conteúdo e purged quando você o destruiu. O estado da tarefa expired significa algo totalmente diferente: a geração excedeu o tempo e não produziu nada. Tentar novamente ajuda apenas nesse segundo caso.

Enviar arquivos de referência

Uma imagem, um vídeo ou um arquivo de áudio de referência pode chegar a uma tarefa de três maneiras. Uma URL HTTPS pública deve retornar o próprio arquivo: um link para uma página de compartilhamento (drive na nuvem, álbum de fotos, publicação em rede social) retorna uma página web, e a tarefa falha com invalid_asset, então baixe o arquivo e envie-o. Uma imagem pequena (até 1 MiB) pode ser incluída como URI de dados base64. Arquivos privados ou grandes devem ser enviados pelo SDK, CLI ou Playground, que retorna uma referência privada spicy:// para a tarefa.

Limites de upload: JPEG, PNG, WebP e GIF até 10 MiB; WAV, MP3, WebM, MP4 e MOV até 90 MiB e 600 segundos; um modelo pode aceitar menos. Mantenha uma cópia original se precisar da entrada novamente depois do prazo de um dia. Seu backend só precisa autorizar o upload e registrar a propriedade; o cliente pode enviar os bytes diretamente. O upload é grátis; a geração é uma compra separada. A documentação de mídia cobre o fluxo.

Resultados: obter, depois copiar ou deixar expirar

Um manuscrito e quadros de paisagens convergem em uma única cena projetada.

Envie cada nova solicitação com sua própria chave de idempotência, guarde o ID da tarefa e obtenha o resultado por sondagem ou callback. Recursos prontos trazem uma url assinada; faça o download sem chave de API e envie um User-Agent como Mozilla/5.0, pois o CDN rejeita o agente padrão do urllib do Python com um 403 que não significa que o link expirou. Uma tarefa succeeded ainda pode ter um recurso pending, então continue verificando até a URL estar pronta. Um link expirado pode ser renovado dentro da retenção; a documentação de mídia mostra como.

Vale tratar explicitamente três estados de recurso:

Um modelo somente de texto não tem assets, e seu texto em output.text é apagado no mesmo cronograma; leia-o antes de presumir que existe um arquivo.

A exceção de armazenamento sem cobrança se aplica quando nenhuma saída de uma tarefa pôde ser armazenada inicialmente. Um recurso antigo unavailable sozinho não comprova um reembolso; confira o acerto da cobrança da tarefa original.

Callbacks carregam seu prompt e links assinados dos resultados. Seu endpoint, proxy reverso, rastreador de erros e pipeline de logs recebem material que o próprio SpicyAPI apaga conforme um cronograma, então oculte os corpos dos callbacks nos logs de acesso e faça a cópia em um worker. Verificação de assinatura, deduplicação e novas tentativas estão na documentação de webhooks.

• Seu produto promete uma biblioteca, compartilhamento ou edição posterior: transfira o resultado em streaming para um armazenamento privado que você controla assim que vir o sucesso, registre seu próprio ID de recurso e, se quiser remover a cópia da plataforma, chame Purge depois. Use streaming em vez de carregar um vídeo grande inteiro na memória e torne a gravação no destino idempotente por tarefa e recurso.
• Entrega única: não copie. Mostre o resultado, informe ao cliente por quanto tempo ele dura e deixe que o prazo de retenção, ou um X-Spicy-Retention curto, o remova.

Uma referência enviada pelo usuário não é um material de marketing, e um resultado bem-sucedido não é consentimento para publicá-lo. Só marque algo como “salvo pelo cliente” depois de confirmar sua própria cópia.

Quando algo falha

Manter logs úteis sem manter material criativo

Verifique estas rotas de cópias acidentais:

• Relatórios de erros e logs de acesso: oculte prompts, tickets e links assinados; evite registrar os corpos das rotas de mídia.
• Análise e filas: use IDs opacos de operação, tarefa e recurso em vez de URLs ou nomes de arquivos, inclusive no armazenamento de mensagens não entregáveis.
• Exportações do suporte e entrega pública: confira capturas de tela, metadados de páginas e emails. Direcione os clientes a uma página autenticada que emita um link novo após verificar o acesso.
• Seu armazenamento e backups: aplique sua própria política de exclusão. Um link expirado não pode revogar um arquivo que alguém já baixou.

O que as configurações de retenção não podem prometer

• O modelo vê o prompt. O modelo que executa a solicitação recebe o texto em claro, então as configurações do SpicyAPI controlam apenas por quanto tempo o próprio SpicyAPI mantém algo. Não envie material desnecessário.
• Purge é uma solicitação de exclusão assíncrona. Confirme o estado de conteúdo retornado e a conclusão da exclusão da mídia. A limpeza do ciclo de vida do armazenamento e a rotação de backups têm prazos separados; suas próprias cópias e backups também precisam de sua própria operação de exclusão. Os registros de cobrança permanecem em qualquer caso.

Se precisar de outro período de retenção no contrato, converse sobre isso antes de assinar em vez de deduzi-lo de uma página da documentação.

Perguntas frequentes

Posso usar uma URL temporária de upload como URL de imagem em uma solicitação de geração?

Não. A URL de upload apenas autoriza a gravação direta. Envie, confirme e coloque a URI spicy:// confirmada em um campo que o esquema atual do modelo identifique como campo de upload.

Posso manter um vídeo gerado no SpicyAPI por mais de 14 dias?

Para resultados de API, SDK e Playground, não: o limite é cerca de 14 dias. Mídias de curtas-metragens do Studio têm um limite separado de cerca de 60 dias. Copie o arquivo para seu armazenamento após o sucesso para ter acesso por mais tempo.

Purge reembolsa a tarefa?

Não. Purge remove apenas o conteúdo; a cobrança e o registro da tarefa permanecem.

Um webhook pode substituir totalmente a sondagem?

Pode ser o caminho principal, com uma verificação de reconciliação limitada para entregas perdidas. Use o request_id da entrega e o ID da tarefa como chaves do seu manipulador.

Posso colocar um link de resultado em um email?

Evite. Emails são encaminhados e arquivados muito depois de um link de curta duração expirar. Direcione os clientes a uma página autenticada que confira o acesso e emita um link novo.

O que deve acontecer quando um cliente exclui um resultado salvo?

Exclua ou revogue sua própria cópia e seu caminho de entrega e mantenha um registro de que o fez. A cópia da plataforma segue seu próprio cronograma; use Destroy outputs se ela precisar desaparecer antes.

Verificar uma tarefa existente pelo código

Instale spicyapi, defina SPICY_API_KEY e TASK_ID e execute esta verificação somente de leitura. Ela não cria uma geração nem exclui conteúdo.

import json
import os
from spicyapi import SpicyClient

client = SpicyClient()
task = client.get_task(os.environ["TASK_ID"])
print(json.dumps({"taskId": task["taskId"], "state": task["state"],
    "contentState": task.get("contentState"), "retention": task.get("retention"),
    "mediaDeletionPending": task.get("mediaDeletionPending")}, indent=2))

A referência de retenção cobre as configurações da solicitação e o contrato de exclusão.

Deixe um Agent cuidar da chamada

Delegue uma verificação de armazenamento quando já tiver um ID de tarefa; não é necessária uma nova geração.

• CLI: npx @spicyapi/cli tasks get "$TASK_ID" lê os prazos atuais. Veja o guia da CLI.
• MCP: peça a spicyapi_task_get que inspecione essa tarefa. Use spicyapi_task_purge somente após aprovar explicitamente a destruição do conteúdo; o guia de MCP cobre a confirmação.
• Skill: após npx skills add spicyapi-ai/spicy-skill, peça a $spicyapi que inspecione a retenção da tarefa e explique o que vai expirar. Veja o guia da Skill.