Polling e webhooks da PiAPI: processe a conclusão com confiança

Uma solicitação de imagem ou vídeo aceita ainda precisa de um fluxo de conclusão. Nas tarefas da API unificada da PiAPI, salve o ID, observe o estado final e processe a saída específica do modelo. Polling funciona bem na primeira integração; webhooks permitem que o backend reaja ao término.

1. Salve o ID e limite o polling

Após criar a tarefa, persista data.task_id junto ao ID do seu trabalho. Consulte a mesma tarefa com a chave API do servidor. Uma resposta HTTP bem-sucedida não comprova o fim da geração: verifique data.status.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

Para completed, valide data.output conforme o modelo; para failed, registre data.error. Limite tentativas e aumente os intervalos com variação aleatória. O prazo de espera da aplicação é uma escolha local: esgotá-lo não prova falha ou cancelamento da tarefa remota. Preserve o ID para reconciliar o estado depois.

2. Adicione um callback autenticado

Mescle o trecho abaixo a um corpo válido de criação de tarefa, preservando os campos existentes de configuração. Use um endpoint HTTPS público e um segredo do armazenamento seguro do backend. A documentação informa que a PiAPI envia esse segredo no cabeçalho x-webhook-secret; valide-o antes de aceitar a notificação.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

O JSON do webhook contém timestamp e data. Confira se a tarefa pertence à aplicação, grave o evento de forma durável ou em uma fila persistente e retorne 2xx rapidamente. Execute downloads e outras operações demoradas fora do manipulador HTTP. Preveja duplicatas: a documentação descreve novas tentativas quando não recebe uma resposta de sucesso.

3. Una polling e callbacks

Use o mesmo manipulador de conclusão nos dois caminhos. Uma restrição persistente de unicidade sobre o ID e a ação final evita notificações duplicadas ou dois trabalhos subsequentes. Um timestamp sozinho não identifica eventos de tarefas diferentes. Ignore atualizações antigas após o estado final e permita repetir o worker com segurança depois de uma falha.

Se o callback não chegar ou o estado for incerto, consulte novamente o ID salvo. Um timeout de consulta não é motivo para criar cegamente outra tarefa paga. Separe erros de transporte de uma falha confirmada da tarefa e reconcilie antes de decidir reenviar.

4. Verifique os cenários de falha

Antes da implantação, repita um callback, envie um segredo incorreto, atrase a entrega e simule a reinicialização do worker. Cada tarefa concluída deve produzir um único resultado durável; cada falha deve manter seu erro. Depois siga o guia de armazenamento de saídas.

Referências: esquema da API unificada, exemplo de consulta de tarefa e documentação de webhooks. Os exemplos ilustram a integração, não um benchmark de geração real.