Guia de integração GloopAPI
Tarefas assíncronas e idempotência
Recupere tarefas e trate envios desconhecidos.
Uma chave de idempotência representa uma operação de negócio do aplicativo. Antes de enviar, salve de forma persistente o corpo da solicitação, a identidade da chave de API e a chave de solicitação. Repetições devem usar a mesma chave e a mesma entrada normalizada. Alterar a solicitação com a mesma chave causa conflito; trocar a chave cria uma nova operação cobrável.
Cotação e criação
Para imagens e vídeos persistentes, consulte primeiro o catálogo de recursos, envie ou importe as entradas, obtenha uma cotação e confirme explicitamente a criação. Cotações de imagem e vídeo valem por 60 segundos; as de ferramentas, por 300 segundos. O prazo real é o expires_at do servidor. Cotações não enviam nada ao serviço nem geram cobranças. Para chamadas novas ainda não enviadas, obtenha outra cotação se ela expirar ou as entradas/configurações mudarem e confira o novo custo antes de criar. Se a solicitação já foi enviada mas o resultado é desconhecido, não altere a cotação nem a solicitação originais.
Cotações de imagem não bloqueiam os recursos de entrada; a criação os valida novamente. Vídeos só permitem um preset completo e quadros gerenciados compatíveis com o modo atual. Vídeos persistentes enviam explicitamente retention: "persistent"; vídeos comuns continuam seguindo seu próprio contrato de entrada por URL.
Decisões para envios desconhecidos
Após obter um ID de tarefa, consulte apenas a tarefa original. Se houver timeout sem receber um ID, use o endpoint de recuperação com a chave de solicitação original para imagens e vídeos persistentes. Se o registro original existir, continue acompanhando-o. Se o status for unknown, submission_unknown, submission_state_unknown, billing_review ou aguardando revisão, não o trate como falha ou reembolso e não gere novamente com outra chave.
Para ferramentas com run_id, consulte com a chave de API original. Se a resposta de criação for perdida e não houver run_id, repita POST /v1/tool-runs usando a chave de API, o Idempotency-Key e o corpo completo originais, mantendo quote_id/version/input/max_cost_usd. Uma execução aceita recupera diretamente o registro original, sem depender de nova cotação ou das opções atuais e sem reenviar ao serviço. O histórico é ordenado por created_at decrescente e id decrescente; devolva next_cursor sem alterações. A paginação não é um retrato fixo; atualize a primeira página para ver registros novos anteriores ao cursor. A clonagem de áudio não tem um endpoint equivalente de recuperação por chave de solicitação. Preserve evidências e investigue envios desconhecidos; não aplique a eles a recuperação de imagens.
Três estados independentes
Avalie separadamente o sucesso da geração, a liquidação da cobrança e a preparação do armazenamento. Imagens podem ter sucesso parcial; ferramentas podem concluir sem uso final confirmado; vídeos podem ser gerados mas falhar ao salvar. Os processos em segundo plano continuam as tarefas persistentes; fechar o navegador ou parar as consultas do cliente não as cancela.
O cancelamento é apenas uma solicitação: pode não ser compatível ou chegar tarde demais. Continue acompanhando o status final e a cobrança. retry/archive-retry do armazenamento apenas salva o resultado original; não gera conteúdo novo. Excluir uma tarefa exige estado terminal e cobrança finalizada; os registros de idempotência e as evidências de cobrança permanecem após a exclusão.
Após obter o resultado, verifique se o armazenamento está ready antes de solicitar a URL temporária de download. A expiração de URLs temporárias do serviço pode tornar o arquivamento irrecuperável. Não esconda um erro de salvamento da tarefa original gerando novamente. Consulte Faturamento e Tratamento de erros.