Salve arquivos de IA: da URL da PiAPI ao armazenamento durável

Uma geração concluída entrega um resultado, mas a URL hospedada pelo provedor não é uma biblioteca permanente. Se os usuários precisarem abrir, editar ou baixar o resultado depois, copie o arquivo para um armazenamento sob seu controle e acompanhe a cópia separadamente da geração.

1. Leia a saída do modelo utilizado

Consulte o ID salvo e exija data.status igual a completed antes de extrair arquivos. O formato de data.output varia conforme o modelo e a tarefa. Use o exemplo de consulta correspondente; não presuma uma URL única de imagem ou vídeo no nível superior de todas as respostas.

Por exemplo, a resposta documentada do Kling contém um array works com recursos de vídeo. Outros modelos usam outros campos. Salve ID, modelo, tipo de tarefa, horário de conclusão e índice do recurso selecionado junto ao trabalho para recuperar o mesmo resultado nas novas tentativas.

2. Copie logo e confira a retenção por serviço

A documentação de armazenamento da PiAPI descreve regras diferentes por serviço e local de hospedagem. Algumas entradas definem prazos curtos; outras dependem da política da CDN do provedor. A página também inclui serviços antigos. Não aplique um prazo a todos os modelos atuais nem interprete a ausência de prazo como retenção ilimitada.

Após a conclusão, inicie uma cópia em segundo plano com webhook ou polling. Persista o trabalho antes de confirmar o callback. A sequência abaixo representa estados de armazenamento da sua aplicação, não estados da API de tarefas PiAPI.

generation completed → copy queued → downloading → verified → saved
                                      ↘ copy failed → retry copy

3. Valide os bytes antes de marcar como salvo

Baixe a URL do resultado sem encaminhar sua chave API PiAPI. Restrinja destinos, valide redirecionamentos e defina limites de tamanho e tempo. Confira status HTTP, quantidade real de bytes, tipo de mídia esperado e legibilidade básica. Uma página de erro HTML com status 200 não é um vídeo salvo.

Grave em um objeto temporário, calcule um checksum e publique o objeto final somente após validar. Use uma chave estável baseada no ID da tarefa e no índice do recurso. Registre chave, bytes, checksum e horário de gravação; disponibilize uma URL própria controlada conforme sua política de acesso.

4. Repita o armazenamento separadamente da geração

Se a cópia falhar, mantenha a geração como concluída e tente copiar novamente enquanto a origem estiver disponível. Um registro único persistente evita mídias duplicadas. Se a URL não puder mais ser lida, consulte a tarefa e sua saída atual; isso não garante recuperar um arquivo expirado. Teste eventos repetidos, downloads parciais e URLs indisponíveis antes da implantação.

Referências: armazenamento de saídas, consulta de tarefa Kling e webhooks. Este é um padrão de armazenamento da aplicação, não uma promessa de arquivamento pela PiAPI.