文档

API 参考

创建工具运行

POST/v1/tool-runs

统一支持 flat 常量按次、input 按输入预计算和 usage 按最终用量。pricing.quote_required 决定是否必须报价，requires_usage 决定是否必须提供费用上限并等待权威最终用量；二者不由 schema_version 推断。metered_pricing 关闭时仅限制需要最终用量的新调用，常量/输入规则若不需要最终用量仍可使用。当前 Key 需具备工具授权，运行身份和结果以原 Key 为界。工具总开关关闭时目录为空；匿名目录不能作为可执行授权。 新调用需要非空 version/input 和 Idempotency-Key。创建回包丢失且无 run_id 时，用原 API Key、原 Idempotency-Key 和原完整请求体重放此操作，恢复既有运行，不重新报价或修改费用上限；已接受运行重放不依赖当前开关或报价有效期。已有 run_id 只查询原运行；未知提交禁止换键新建。

报价后执行

从工具详情取得精确 version、input_schema 与 pricing。mode=flat 是常量按次价，mode=input 是按输入预计算，mode=usage 是按最终用量；规则的 schema_version 只表示存储格式。

quote_required=true 的新调用先报价，核对响应回显的 tool_id/version，保存 quote_id 和原请求。requires_usage=true 时还必须提供不低于 maximum_usd 的 max_cost_usd；其余运行可选费用上限，但提供后同样检查。常量且无需最终用量的运行可以直接执行；按输入规则必须报价但可无需最终用量结算。

报价固定原来源；默认来源后来改变时，只要原来源和配置仍有效，原报价仍使用原来源。未提交的新调用遇到 quote_expired、quote_stale 或 invalid_quote 可核对输入后重新报价。执行成功但 billing 仍 reserved 时，应继续查询最终用量，不能按输出成功自行认定结清。

回包丢失时恢复

发送前保存原 API Key 身份、Idempotency-Key 和完整请求体。如果创建响应丢失且没有 run_id，使用同一 Key、同一请求键和原完整请求重放 POST /v1/tool-runs；保持原 quote_id 与 max_cost_usd，不重新报价，也不更换键。已有运行优先返回原记录，不重复执行任务，即使报价后来过期或新调用开关关闭仍可恢复。已经取得 run_id 后只 GET 原运行。

幂等冲突必须核对原请求；不要自动改键新建收费操作。见错误处理、计费和异步恢复。

鉴权与权限

使用当前 GloopAPI Key。模型、功能与权限以当前 Key 的目录及接口说明为准。

Authorization: Bearer $GLOOP_API_KEY

鉴权方案： BearerAuth

请求

请求头

  • Idempotency-Keystring必填

    同 Key 保存原请求意图；网络中断先恢复查询，未知状态禁止盲重发。

    最短长度
    1
    最长长度
    191

请求体 · application/json

类型
object
必填字段
tool_idversioninput
额外属性
false

请求体必填

  • quote_idstring选填

    pricing.quote_required=true 时新运行必填有效报价；常量销售且无需最终用量时可省略。提供报价时始终核验绑定。

  • tool_idstring必填

    当前 Key 可执行目录中的工具 ID。

  • versionstring必填

    契约/能力或工具版本；运行使用目录返回的工具版本。

    最短长度
    1
    匹配规则
    ".*\\S.*"
  • inputunknown必填

    必须通过该工具 version 的 input_schema；只接受规范 JSON，禁止管理员 route_id 等额外字段。

  • max_cost_usdstring选填允许 null

    pricing.requires_usage=true 时新运行必须提供有效非 null 十进制美元预算，不低于报价 maximum_usd；其余可选但提供时同样检查。预算仅在创建运行时检查。

响应与错误

HTTP 200

运行状态为 succeeded 或 failed 时返回 200，适用于首次同步返回和原请求的幂等恢复；succeeded 仍可能伴随 billing.status=reserved 等待最终用量结算，HTTP 200 不表示账务已结清。

application/json

类型
object
必填字段
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstring必填

    该对象的公开标识符；用于对应详情路径。

  • tool_idstring必填

    当前 Key 可执行目录中的工具 ID。

  • versionstring必填

    契约/能力或工具版本；运行使用目录返回的工具版本。

  • statusstring必填

    submitting/running/submission_unknown/succeeded/failed；submission_unknown 表示提交结果未知，不得换 Idempotency-Key 重发。

  • outputunknown必填

    工具 output_schema 定义的 JSON；过期后不可假定结果仍存在。

  • error_codestring选填

    可用于分支处理的公开错误码。

  • billingobject必填

    独立账务状态，不用生成状态代替。

    billing 子字段（7）
    • review_requiredboolean选填

      账务证据需人工复核。

    • reasonstring选填

      不可操作或账务复核的公开理由。

    • usageunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • breakdownunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • statusstring必填

      对象当前状态；必须与账务和保存阶段分别判断。

    • reserved_usdstring必填

      最大预留美元金额字符串。

    • charged_usdstring必填

      当前确认收取美元金额字符串。

    allOf 分支 1

    类型: object

    分支必填： status, reserved_usd, charged_usd

    • review_requiredboolean选填

      账务证据需人工复核。

    • reasonstring选填

      不可操作或账务复核的公开理由。

    • usageunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • breakdownunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • statusstring必填

      对象当前状态；必须与账务和保存阶段分别判断。

    • reserved_usdstring必填

      最大预留美元金额字符串。

    • charged_usdstring必填

      当前确认收取美元金额字符串。

  • result_expiredboolean必填

    结果是否已过期；账务/幂等记录仍保留。

  • created_atinteger必填

    Unix 秒创建时间。

  • updated_atinteger必填

    Unix 秒最后更新时间。

HTTP 202

运行状态为 submitting、running 或 submission_unknown；请求已接受，账务仍需按 billing 独立判断。

application/json

类型
object
必填字段
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstring必填

    该对象的公开标识符；用于对应详情路径。

  • tool_idstring必填

    当前 Key 可执行目录中的工具 ID。

  • versionstring必填

    契约/能力或工具版本；运行使用目录返回的工具版本。

  • statusstring必填

    submitting/running/submission_unknown/succeeded/failed；submission_unknown 表示提交结果未知，不得换 Idempotency-Key 重发。

  • outputunknown必填

    工具 output_schema 定义的 JSON；过期后不可假定结果仍存在。

  • error_codestring选填

    可用于分支处理的公开错误码。

  • billingobject必填

    独立账务状态，不用生成状态代替。

    billing 子字段（7）
    • review_requiredboolean选填

      账务证据需人工复核。

    • reasonstring选填

      不可操作或账务复核的公开理由。

    • usageunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • breakdownunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • statusstring必填

      对象当前状态；必须与账务和保存阶段分别判断。

    • reserved_usdstring必填

      最大预留美元金额字符串。

    • charged_usdstring必填

      当前确认收取美元金额字符串。

    allOf 分支 1

    类型: object

    分支必填： status, reserved_usd, charged_usd

    • review_requiredboolean选填

      账务证据需人工复核。

    • reasonstring选填

      不可操作或账务复核的公开理由。

    • usageunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • breakdownunknown选填

      由所选工具的 schema 或协议定义的 JSON 值；不假定固定字段。

    • statusstring必填

      对象当前状态；必须与账务和保存阶段分别判断。

    • reserved_usdstring必填

      最大预留美元金额字符串。

    • charged_usdstring必填

      当前确认收取美元金额字符串。

  • result_expiredboolean必填

    结果是否已过期；账务/幂等记录仍保留。

  • created_atinteger必填

    Unix 秒创建时间。

  • updated_atinteger必填

    Unix 秒最后更新时间。

HTTP 400

请求字段或参数无效。

application/json

类型
object
必填字段
error

HTTP 401

Key 缺失、无效、过期或已撤销。

application/json

类型
object
必填字段
error

HTTP 403

IP、账户、模型或工具权限不足。

application/json

类型
object
必填字段
error

HTTP 404

对象/能力不可用，或功能开关关闭。

application/json

类型
object
必填字段
error

HTTP 409

幂等/报价冲突、对象未准备或仍被引用。

application/json

类型
object
必填字段
error

HTTP 429

请求/队列限流。

application/json

类型
object
必填字段
error

HTTP 500

鉴权或数据存储内部失败。

application/json

类型
object
必填字段
error

HTTP 503

服务、定价或存储不可用。

application/json

类型
object
必填字段
error

接口说明

示例针对 requires_usage=true 的工具：替换 quote_id 和 max_cost_usd，预算须为有效十进制美元字符串且不低于本次报价 maximum_usd；0.01 仅为说明值。按输入规则需要报价但无需最终用量时预算可选；常量且无需最终用量的运行报价和预算均可选。发送前保存原 Key 身份、请求键和完整请求体，丢失回包沿用它们恢复。