Documentação

Referência da API

Criar execução de ferramenta

POST/v1/tool-runs

Aceita flat constante por chamada, input calculado previamente pelas entradas e usage pelo uso final. pricing.quote_required determina se a cotação é obrigatória; requires_usage, se limite de custo e uso final oficial são exigidos. Nenhum é inferido de schema_version. Com metered_pricing desativado, só novas chamadas que exigem uso final são restritas; regras constantes/por entrada sem esse requisito continuam disponíveis. A chave atual precisa de autorização de ferramentas; identidade e resultados são limitados à chave original. Com a opção geral desativada, o catálogo fica vazio; catálogo anônimo não autoriza execução. Novas chamadas exigem version/input não vazios e Idempotency-Key. Se a resposta for perdida sem run_id, repita com chave de API, Idempotency-Key e corpo completo originais para recuperar a execução, sem recotar ou mudar o limite de custo. Repetir execução aceita não depende de opções atuais nem validade da cotação. Com run_id, consulte só a original; não crie com outra chave em envio desconhecido.

Executar após cotar

Obtenha version, input_schema e pricing exatos nos detalhes da ferramenta. mode=flat é preço constante por chamada; mode=input é calculado previamente pelas entradas; mode=usage usa o consumo final. schema_version só descreve o formato de armazenamento.

Chamadas novas com quote_required=true precisam cotar primeiro. Confira tool_id/version retornados e salve quote_id e a solicitação original. Com requires_usage=true, max_cost_usd deve ser no mínimo maximum_usd. Para outras execuções, o limite é opcional, mas também é verificado se informado. Execuções de preço constante sem uso final podem executar diretamente; regras por entrada exigem cotação mas podem liquidar sem uso final.

A cotação fixa a origem original. Mesmo que a padrão mude, a original continua sendo usada enquanto ela e sua configuração forem válidas. Em quote_expired, quote_stale ou invalid_quote, uma chamada nova ainda não enviada pode ser recotada após conferir entradas. Se a execução tiver sucesso mas billing continuar reserved, consulte o uso final; sucesso da saída não comprova liquidação.

Recuperar resposta perdida

Antes de enviar, preserve a identidade da chave de API, Idempotency-Key e corpo completo originais. Se a resposta for perdida sem run_id, repita POST /v1/tool-runs com a mesma chave de API, chave de solicitação e corpo completo original. Preserve quote_id e max_cost_usd; não recote nem troque chaves. Uma execução existente retorna primeiro seu registro original sem chamar novamente o serviço; ela pode ser recuperada mesmo após a cotação expirar ou novas chamadas serem desativadas. Depois de obter run_id, use apenas GET na execução original.

Conflitos de idempotência exigem conferir a solicitação original; não troque automaticamente a chave para criar outra operação cobrável. Consulte Tratamento de erros, Faturamento e Recuperação assíncrona.

Autenticação e permissões

Use sua chave atual do GloopAPI. Modelos, recursos e permissões disponíveis dependem do catálogo da chave e da documentação do endpoint.

Authorization: Bearer $GLOOP_API_KEY

Esquemas de autenticação: BearerAuth

Solicitação

Cabeçalhos da solicitação

  • Idempotency-KeystringObrigatório

    Preserve a intenção original com a mesma chave; após interrupção, consulte a recuperação primeiro. Não reenvie às cegas estados desconhecidos.

    Comprimento mínimo
    1
    Comprimento máximo
    191

Corpo da solicitação · application/json

Tipo
object
Campos obrigatórios
tool_idversioninput
Propriedades adicionais
false

Corpo da solicitação obrigatório

  • quote_idstringOpcional

    Novas execuções com pricing.quote_required=true exigem cotação válida; pode ser omitida em venda constante sem uso final. O vínculo de qualquer cotação informada é sempre verificado.

  • tool_idstringObrigatório

    ID da ferramenta no catálogo executável da chave atual.

  • versionstringObrigatório

    Versão do contrato/recurso ou ferramenta; a execução usa a versão retornada pelo catálogo.

    Comprimento mínimo
    1
    Padrão
    ".*\\S.*"
  • inputunknownObrigatório

    Deve cumprir input_schema dessa version; apenas JSON normalizado, sem campos extras como route_id de administrador.

  • max_cost_usdstringOpcionalPermite null

    Novas execuções com pricing.requires_usage=true exigem orçamento decimal USD válido, não null, igual ou maior que maximum_usd da cotação. É opcional nas demais, mas também verificado se informado. Só é verificado na criação.

Respostas e erros

HTTP 200

Retorna 200 com succeeded ou failed, tanto na resposta síncrona inicial quanto na recuperação idempotente. succeeded pode ter billing.status=reserved aguardando uso final; HTTP 200 não implica liquidação.

application/json

Tipo
object
Campos obrigatórios
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObrigatório

    Identificador público do objeto, usado na sua rota de detalhes.

  • tool_idstringObrigatório

    ID da ferramenta no catálogo executável da chave atual.

  • versionstringObrigatório

    Versão do contrato/recurso ou ferramenta; a execução usa a versão retornada pelo catálogo.

  • statusstringObrigatório

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica resultado de envio desconhecido. Não reenvie com outro Idempotency-Key.

  • outputunknownObrigatório

    JSON definido por output_schema da ferramenta; não presuma que ainda exista após expirar.

  • error_codestringOpcional

    Código público de erro para decisões de fluxo.

  • billingobjectObrigatório

    Status de cobrança independente, não substituível pelo status de geração.

    Campos filhos de billing (7)
    • review_requiredbooleanOpcional

      As evidências de cobrança exigem revisão manual.

    • reasonstringOpcional

      Motivo público de ação indisponível ou revisão de cobrança.

    • usageunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • breakdownunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • statusstringObrigatório

      Status atual do objeto; avalie separadamente da cobrança e do salvamento.

    • reserved_usdstringObrigatório

      Reserva máxima USD como string.

    • charged_usdstringObrigatório

      Valor USD confirmado atualmente, como string.

    Ramificação allOf 1

    Tipo: object

    Obrigatório nesta ramificação: status, reserved_usd, charged_usd

    • review_requiredbooleanOpcional

      As evidências de cobrança exigem revisão manual.

    • reasonstringOpcional

      Motivo público de ação indisponível ou revisão de cobrança.

    • usageunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • breakdownunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • statusstringObrigatório

      Status atual do objeto; avalie separadamente da cobrança e do salvamento.

    • reserved_usdstringObrigatório

      Reserva máxima USD como string.

    • charged_usdstringObrigatório

      Valor USD confirmado atualmente, como string.

  • result_expiredbooleanObrigatório

    Se o resultado expirou; cobrança e idempotência permanecem.

  • created_atintegerObrigatório

    Data de criação em segundos Unix.

  • updated_atintegerObrigatório

    Última atualização em segundos Unix.

HTTP 202

Status submitting, running ou submission_unknown; solicitação aceita, mas billing deve ser avaliado separadamente.

application/json

Tipo
object
Campos obrigatórios
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObrigatório

    Identificador público do objeto, usado na sua rota de detalhes.

  • tool_idstringObrigatório

    ID da ferramenta no catálogo executável da chave atual.

  • versionstringObrigatório

    Versão do contrato/recurso ou ferramenta; a execução usa a versão retornada pelo catálogo.

  • statusstringObrigatório

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica resultado de envio desconhecido. Não reenvie com outro Idempotency-Key.

  • outputunknownObrigatório

    JSON definido por output_schema da ferramenta; não presuma que ainda exista após expirar.

  • error_codestringOpcional

    Código público de erro para decisões de fluxo.

  • billingobjectObrigatório

    Status de cobrança independente, não substituível pelo status de geração.

    Campos filhos de billing (7)
    • review_requiredbooleanOpcional

      As evidências de cobrança exigem revisão manual.

    • reasonstringOpcional

      Motivo público de ação indisponível ou revisão de cobrança.

    • usageunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • breakdownunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • statusstringObrigatório

      Status atual do objeto; avalie separadamente da cobrança e do salvamento.

    • reserved_usdstringObrigatório

      Reserva máxima USD como string.

    • charged_usdstringObrigatório

      Valor USD confirmado atualmente, como string.

    Ramificação allOf 1

    Tipo: object

    Obrigatório nesta ramificação: status, reserved_usd, charged_usd

    • review_requiredbooleanOpcional

      As evidências de cobrança exigem revisão manual.

    • reasonstringOpcional

      Motivo público de ação indisponível ou revisão de cobrança.

    • usageunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • breakdownunknownOpcional

      Valor JSON definido por schema ou protocolo da ferramenta; sem presumir campos fixos.

    • statusstringObrigatório

      Status atual do objeto; avalie separadamente da cobrança e do salvamento.

    • reserved_usdstringObrigatório

      Reserva máxima USD como string.

    • charged_usdstringObrigatório

      Valor USD confirmado atualmente, como string.

  • result_expiredbooleanObrigatório

    Se o resultado expirou; cobrança e idempotência permanecem.

  • created_atintegerObrigatório

    Data de criação em segundos Unix.

  • updated_atintegerObrigatório

    Última atualização em segundos Unix.

HTTP 400

Campos ou parâmetros de solicitação inválidos.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 401

A chave está ausente, inválida, expirada ou revogada.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 403

Permissões insuficientes de IP, conta, modelo ou ferramenta.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 404

Objeto/recurso indisponível ou função desativada.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 409

Conflito de idempotência/cotação, objeto não pronto ou ainda referenciado.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 429

Limite de solicitações/fila.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 500

Falha interna de autenticação ou armazenamento de dados.

application/json

Tipo
object
Campos obrigatórios
error

HTTP 503

Serviço, preços ou armazenamento indisponíveis.

application/json

Tipo
object
Campos obrigatórios
error

Notas do endpoint

Exemplo para ferramentas com requires_usage=true: substitua quote_id e max_cost_usd. O orçamento deve ser uma string decimal USD válida não inferior ao maximum_usd da cotação; 0.01 é ilustrativo. Em regras por entrada que exigem cotação mas não uso final, o orçamento é opcional; em preço constante sem uso final, ambos são opcionais. Salve a identidade da chave, a chave de solicitação e o corpo completo originais antes de enviar; reutilize-os se a resposta for perdida.

Pronto para criar? Abra console para criar uma chave de API, ou explore recursos.