Saltar para o conteúdo principal

​
Visão geral

Esta página explica cotação, reserva, execução assíncrona, cobrança e artefatos. Acompanhe processos longos pelo ID sem manter a conexão HTTP aberta.

​
Entender execução e cobrança

POST /tools/quote retorna versão de preços, custo mínimo e reserva máxima para a entrada. A cotação é gratuita, sem chamar serviços externos nem reservar fundos. Mantenha tool e arguments da cotação e adicione:
  • priceVersion — Versão de preços da cotação
  • maximumChargeMicros — Reserva máxima da cotação
Se os preços mudarem ou o limite for insuficiente, a solicitação é recusada antes do processamento. Obtenha e revise outra cotação.

​
Reservar e consolidar cobranças

Na aceitação, o máximo é temporariamente reservado do saldo pré-pago em USD. Ao concluir, cobra-se o custo real e devolve-se a parte não utilizada. Falhas e cancelamentos ainda podem cobrar custos externos já incorridos. Nenhuma cobrança automática excede a reserva máxima.

​
Consultar o estado

A aceitação retorna HTTP 202 e um ID. Siga Retry-After: 5 e consulte o mesmo ID a intervalos de pelo menos cinco segundos.

​
Evitar duplicações com idempotência

Uma chave de idempotência evita execuções separadas ao reenviar acidentalmente a solicitação. POST /tools/{tool} pago exige Idempotency-Key. A chave tem 8–128 caracteres: letras, números, ., _, : ou -. Gere uma por solicitação lógica e salve com o ID de execução.
  • Mesma chave API, corpo e chave de idempotência retornam a mesma execução.
  • Alterar corpo ou chave API mantendo a chave de idempotência retorna HTTP 409.
  • Após falha de conexão, reenvie sem alterar corpo ou chave de idempotência.
  • Reenviar um processo needs_review com nova chave cria outra execução paga.
Não receber resposta não prova que a execução não foi aceita. Não crie outra chave com resultado desconhecido.

​
Cancelar uma execução

POST /tools/executions/{id}/cancel solicita parar trabalho ainda não iniciado. A chave criadora ou um ADMIN do projeto pode solicitar. Se o processamento externo já começou, o cancelamento pode não desfazer trabalho ou custos. Verifique cancelRequested, o status final e chargedMicros.

​
Obter artefatos

Imagens, áudio e vídeo gerados aparecem em output.artifacts com ID, formato, tamanho, hash e validade. O resultado não inclui arquivos completos nem URLs permanentes. GET /tools/executions/{id}/artifacts/{artifactId}/download fornece uma URL válida por até cinco minutos. Arquivos armazenados expiram após 30 dias. Mesmo temporárias, essas URLs dão acesso a dados privados. Não registre nem publique, e não acrescente a chave Developer Platform.

​
Páginas relacionadas

Estas páginas detalham a primeira execução e os endpoints.