QVeris
接入我正在用的 AI
文档目录

QVeris REST API 文档

版本：2026-09-29.2

公开 REST API 暴露核心 Agent 路径：

协议动作Endpoint成本行为
DiscoverPOST /search免费；返回排序后的能力和可选成本信号
InspectPOST /tools/by-ids免费；返回完整 schema、示例、质量信号和成本信号
ProbePOST /tools/probe免费；校验参数并返回调用前报价，但不执行能力
CallPOST /tools/execute可能按所选能力的 billing_rule 消耗积分
调用历史GET /auth/usage/history/v2最终请求状态和扣费结果
积分账本GET /auth/credits/ledger最终积分余额变动

请将示例中的 srch_...、exec_...、led_... 替换为你自己 API 响应中返回的 ID。

聚焦参考页：Discover、Inspect、Probe、Call。侧栏和公共 OpenAPI JSON 覆盖所有已发布操作。

Base URL

text
https://qveris.ai/api/v1

身份认证

在 Authorization 请求头中发送 API key：

text
Authorization: Bearer YOUR_API_KEY

Agent 匿名试用注册（推荐 Agent 使用）

需要立即获得 Key、又不想等待人工邮箱验证的 Agent，可以先走匿名试用。试用账号有效期 7 天，赠送 50 积分，可调用 search / execute，但不能调用模型网关。

bash
curl -X POST https://qveris.ai/api/v1/agent/anonymous-register \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"demo-agent"}'

请保存返回的 api_key 与 claim_code；API Key 只会展示一次。

需要把试用账号转为正式账号时，用邮箱认领：

bash
# 第 1 步：绑定邮箱并接收 6 位验证码
curl -X POST https://qveris.ai/api/v1/agent/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_code":"<claim_code>","email":"operator@example.com"}'

# 第 2 步：验证后原有 API Key 继续有效
curl -X POST https://qveris.ai/api/v1/agent/claim-verify \
  -H "Content-Type: application/json" \
  -d '{"claim_code":"<claim_code>","email":"operator@example.com","code":"123456"}'

运营人员也可以直接在官网打开认领页面认领。认领码不能绑定到已属于正式账号的邮箱。

成本与 session 合同

Discover、Inspect 和 Probe 免费。Discover 与 Inspect 可能返回 expected_cost、旧字段 cost 或 billing_rule；Probe 会在花费积分前校验所选参数并返回零成本报价。

Discover 或 Inspect 返回的每项能力，以及每个成功的 Probe，都包含 verification_status、对应的 verification 检查证据和 execution_restrictions。只有 verified 表示完整证据仍在有效期内。Verification 是证据声明，不是执行的必要条件；没有明确阻断时，候选能力可以尝试调用。资格、许可、商业用途或地域声明缺失表示未知，而非禁止；service_regions: null 表示没有显式地域限制。callable: true 表示当前目录证据不阻止尝试 Call，不保证实时授权、可用性或计费一定成功。请根据 blocked_actions 和 next_action 处理实际阻断；只有参数或报价需要预检时才使用 Probe。实时 Probe 的肯定结果可让限制信息不完整的候选进入 Call，但明确的权限、地域、许可、scope、工具可用性或预算阻断仍优先。旧字段 callable 不决定 Discover 或 Inspect 是否可见。

旧目录结果若提供固定的 billing_rule 每次调用价格，即使 price_certainty 仍为 estimated，也可以直接尝试调用；目录价格并非预留报价。可变计费或 Probe 明确返回非精确报价时，仍需确认预算。

默认/full Call 响应可能返回 billing、cost 等紧凑预结算字段。投影响应（summary 和 fields:*）会刻意省略计费内部详情，以保持结构精简。最终结算由调用历史和积分账本报告；客服、对账和用户账单历史应以这些端点为准。

session_id 可选。建议每个用户任务或会话使用一个稳定值，用于追踪、分析和计费上下文。它不是缓存合同，也不承诺缓存复用或 session_cache_hit。

条件化 Discover -> Call 集成契约

请把所选能力的当前契约作为 Call 的可信来源。完整的 Discover 结果足以支持直接调用时，无需额外步骤；只有结果缺少必要契约、元数据可能过期或需要比较候选时才 Inspect，只有参数需要预检或预算决策需要当前报价时才 Probe。

推荐契约：

  1. 为一次用户任务或会话生成稳定的 session_id。
  2. 用能力级查询调用 POST /search。
  3. 保存返回的 search_id。
  4. 按能力、Provider、时效和费用约束选择结果。执行前检查 verification_status，并披露资格、许可、地域、数据截至时间和商业使用限制。不要直接取第一条结果再填入无关样例参数。
  5. 若结果包含完整且当前有效的 params 契约，直接据此构造 parameters。明确的空契约表示真正的零参数能力；契约缺失或不完整则需要 Inspect。业务输入不足时应向用户询问，不要猜测。
  6. 仅在需要 schema 校验或当前报价时调用 POST /tools/probe?tool_id=...。精确 Probe 报价可以满足当前请求的价格就绪检查；没有上限的估算仍需确认预算。Probe 报价不是价格预留或执行授权。
  7. 调用 POST /tools/execute，传入 tool_id、parameters、search_id、session_id；如果是智能体客户端，也传入 model。
  8. 保存 execution_id，用于审计和客服排查。付费 Call 的执行结果未知时不要自动重放。

不要只根据工具名称猜参数。不要复用其他工具、其他 provider 或旧缓存 schema 的参数。如果客户端缓存工具元数据，请使用较短 TTL，或在新搜索返回该工具时刷新 schema。

examples.sample_parameters 只是起步示例，不是完整合同或用户意图。保留 required、enum 和 alternative/one-of 约束，但应使用当前请求中的业务值替换样例值。

对于 LLM/智能体集成，建议在 Call 元数据中传入 model，例如 "model": "gpt-4.1" 或 "model": "deepseek-v4-pro"。这有助于把工具选择、参数生成质量和具体模型关联起来。

安装页的服务/任务上下文

用户选择当前可用的服务或工具后，发现入口可以把公开选择承接到插件页面。这是显式手动承接，不是执行或授权合同：安装页会校验上下文，并允许用户把准确 ID 或 JSON 模板复制给智能体。URL 不得包含请求参数、用户提示词或 API Key。

版本 1 使用以下查询参数：

参数是否必填合同
context_version建议生产方协议版本。缺失时按版本 1 处理；只要最低消费者版本仍受支持，新版本也可继续使用。
context_min_version否能安全解释稳定字段的最低消费者版本。若高于当前消费者版本，则进入刷新状态并保留安全公开 ID。
context_issued_at是Unix 秒时间戳，最多可以比消费者时钟快五分钟。
context_expires_at是Unix 秒时间戳，必须晚于 context_issued_at，且最长有效期为 24 小时。
task_id是公开任务标识符，长度为 1–128 个字符。
service_id条件必填公开服务标识符；service_id 和 tool_id 至少提供一个。
tool_id条件必填Discover 或 Inspect 返回的准确公开工具标识符。
template_id否公开模板标识符；它不是模板内容或提示词。
platform否插件页面已经支持的安装平台标识符。
extensions.<namespace>.<field>否用于前向兼容的公开元数据。名称和值使用受限的公开 ID 字符集；私有数据或疑似凭证会被清除。

公开 ID 必须以 ASCII 字母或数字开头，只能包含 ASCII 字母、数字、.、_、:、/ 或 -。生产者不得在安装 URL 中放入 prompt、query、parameters、payload、api_key、token、authorization、凭证、PII 或其他私有数据；消费者会严格清除。普通未知字段只会被忽略并产生告警，不再让整个交接失效。可安全处理的字段名大小写、首尾空白和等价重复值会被规范化；只有冲突重复、歧义或安全风险才会被拒绝。

示例结构（请生成当前时间戳，不要复用以下字面值）：

text
/plugins?context_version=1&context_issued_at=1800000000&context_expires_at=1800003600&task_id=company-latest-filing&service_id=service.market-data.v1&tool_id=provider.company.lookup.v1&template_id=filing-summary.v1

登录期间，上下文会保留在同站点相对 URL 中。登录返回后，安装页会自动重新校验。过期只会让发现时的可用性、价格和权限等快照失效；安全任务意图以及公开的 service/tool/task/template ID 会继续保留，用于一键重新发现。切换安装平台时也会保留安全公开意图。

可恢复状态和拒绝状态都会返回结构化问题：code、retryable、next_action 与 preserved_safe_fields。消费者应按 next_action 恢复，而不是删除整个交接。安全告警使用 unknown_field_ignored、duplicate_collapsed、newer_version_accepted 等稳定代码。

故障排查：

提示含义处理方式
快照已过期可用性、价格、权限或条件可能已经变化。使用一键工具搜索操作，基于已保留的安全任务意图重新发现。
上下文不完整task_id 缺失/格式错误，或服务/工具标识符均缺失。保留其余安全公开 ID 并重新发现。
快照无效时间戳格式错误、签发时间超出时钟容差、顺序颠倒或有效期超过 24 小时。刷新发现元数据，不要丢弃安全任务意图。
需要刷新版本context_min_version 高于当前消费者。从工具搜索刷新；稳定公开 ID 会继续保留。
上下文有歧义同一个规范字段包含冲突值。解决生产方冲突后再应用交接。
上下文不安全URL 包含凭证、PII、提示词、参数、载荷或其他危险字段。在生产者边界移除私有数据；若凭证曾暴露，请立即轮换。

安装页只负责引导。有效上下文、已复制模板或安装确认不代表服务可用，也不得计为工具调用、有效结果、扣费或结算完成。真正执行前，客户端必须再次严格确认认证、权限、当前价格、限制、参数 schema、provider/上游状态以及必要的用户确认。执行失败后，应根据返回的结构化状态重新发现或刷新，不得静默重放付费调用。

计费透明化合同

QVeris 将调用前估价、执行结果、预结算账单和最终账本结算分开表达。

阶段读取位置重要字段使用方式
调用前估价Discover / Inspectexpected_cost、billing_rule执行能力前向用户展示计价规则。
执行结果Callsuccess、error_message解释 provider/result 是否可用。不要只用 success 判断最终是否扣费。
Provider/result 结果调用审计execution_outcome、reason_code、billable_success不扩展 Call 响应也能查看结构化 provider 和结果分类。
预结算账单默认/full Call 和调用审计billing、pre_settlement_bill、requested_amount_credits展示最终结算、折扣或不扣费规则应用前的请求金额。
最终请求状态调用审计charge_outcome、reason_code、settlement_result、actual_amount_credits判断请求最终是否扣费以及原因。
最终余额变动Credits 账本amount_credits、balance_before、balance_after、execution_id用于账户余额对账和客服排查。

推荐对账流程：

  1. 使用 Discover 或 Inspect 展示 billing_rule / expected_cost。
  2. 调用能力并保存 execution_id 和旧字段 cost；默认/full 客户端也可保存紧凑的 billing。
  3. 查询 /auth/usage/history/v2?execution_id=...，读取 charge_outcome、reason_code、actual_amount_credits 和 credits_ledger_entry_id。
  4. 查询 /auth/credits/ledger 或关联账本行，验证最终带符号的余额变动。

客户端建议：

  • REST 客户端应保留 Call 响应中的 execution_id 和 cost。结构化结果和最终计费详情应从调用审计读取。
  • CLI、MCP 和 SDK 客户端应保持投影 Call 响应精简，只在需要时获取审计详情。
  • 自动化逻辑优先使用审计中的 charge_outcome、reason_code 等稳定机器字段；面向用户的展示可使用 billing_summary 和 error_message。
  • cost 为兼容旧客户端保留。新的计费 UI 应以调用审计和 Credits 账本作为最终结算依据。

限流

已认证请求按账号共享额度，同一账号下的所有 API Key 计入同一限流桶。网站匿名流量按客户端 IP 限流。

动作默认额度
Discover (POST /search)120 次/分钟
Inspect (POST /tools/by-ids)120 次/分钟
Probe (POST /tools/probe)120 次/分钟
Call (POST /tools/execute)200 次/分钟

限流响应包含：

Header说明
X-RateLimit-Limit当前窗口最大请求数
X-RateLimit-Remaining当前窗口剩余请求数
X-RateLimit-Reset当前窗口重置的 Unix 秒级时间戳
Retry-After建议重试等待秒数；429 一定返回

1. 发现能力

text
POST /search

请求

为保证后续步骤可以稳定复现，本示例直接使用工具 ID 查询。实际进行动态发现时，请输入自然语言能力描述，再从返回结果中选择工具。

json
{
  "query": "openweathermap.weather.execute.v1",
  "limit": 10,
  "session_id": "sess_7Q9m"
}
字段类型必填说明
querystring是自然语言能力查询；需要确定性查找时也可传入完整工具 ID
limitinteger否最大结果数；默认 20，范围 1-100
session_idstring否当前用户任务的追踪和计费上下文 ID
viewstring否响应投影：routing 返回精简路由卡和必需的验证、限制字段；full 或缺省返回完整结构。
langstring否响应语言，zh 或 en；缺省按 Accept-Language 协商

成功响应（验证对象从略）

为便于阅读，本流程的 JSON 示例省略了必需的 verification 和 execution_restrictions 对象；完整结构以以下字段说明或 OpenAPI schema 为准。

json
{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true,
          "description": "天气服务接受的地点查询。"
        }
      ],
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": {
        "unit": "request",
        "amount_credits": 5
      },
      "stats": {
        "avg_execution_time_ms": 210.7,
        "success_rate": 0.982
      }
    }
  ],
  "elapsed_time_ms": 245.6,
  "remaining_credits": 995
}

响应字段

字段类型说明
querystring原始搜索查询（如果可用）。
search_idstringDiscover 返回的搜索 id。后续 Inspect 或 Call 可复用该 id。
totalinteger返回的能力结果数量。
resultsarray排序后的能力结果。
elapsed_time_msnumber搜索耗时，单位毫秒。
remaining_creditsnumber/null可用时返回账户剩余积分。
error_messagestring/null业务失败时的错误说明。

能力结果字段

字段类型说明
tool_idstringInspect 和 Call 使用的唯一能力 id。
verification_statusstring证据状态：unverified、verifying、verified、stale、failed 或 restricted。只有 verified 声明证据完整且有效；其他状态仍可见并带恢复指引。
verificationobject策略版本、必需检查、证据时间、测试摘要和质量问题。
execution_restrictionsobject是否可立即调用，以及资格、许可、地域、数据截至时间和商业使用限制。
namestring面向用户的能力名称。
descriptionstring能力说明。
provider_namestring能力提供方名称。
paramsarray参数定义；每一项可包含 name、type、required、description、enum。
examplesobject可用时返回示例参数。
expected_coststring可用时返回面向用户的调用前成本提示。
billing_ruleobject可用时返回结构化成本提示。
stats.avg_execution_time_msnumber历史平均执行耗时，单位毫秒。
stats.success_ratenumber历史成功率，范围 0 到 1。

错误响应

API key 无效：

json
{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_failed",
  "total": 0,
  "results": []
}

积分不足：

json
{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_failed",
  "total": 0,
  "results": [],
  "error_message": "Insufficient credits",
  "remaining_credits": 0
}

触发限流：

json
{
  "status": "failure",
  "status_code": 429,
  "message": "Rate limit exceeded. Please try again later."
}

2. 按 id 检查能力

text
POST /tools/by-ids

Inspect 返回与 Discover 相同的能力结果结构，通常包含更完整的参数和示例。

请求

json
{
  "tool_ids": ["openweathermap.weather.execute.v1"],
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m"
}
字段类型必填说明
tool_idsstring[]是Discover 返回的能力 id
search_idstring否返回该能力的 search id
session_idstring否当前用户任务的追踪和计费上下文 ID
viewstring否响应投影：lean 精简每个能力的元数据以节省模型上下文；full 或缺省返回完整结构

成功响应（验证对象从略）

每项结果还包含 Discover 中说明的必需字段 verification_status、verification 和 execution_restrictions。

json
{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true,
          "description": "天气服务接受的地点查询。"
        }
      ],
      "examples": {
        "sample_parameters": {
          "q": "北京"
        }
      },
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": {
        "unit": "request",
        "amount_credits": 5
      },
      "stats": {
        "avg_execution_time_ms": 210.7,
        "success_rate": 0.982
      }
    }
  ],
  "remaining_credits": 995
}

响应字段

字段类型说明
search_idstring可用时返回与本次检查关联的 search id。
totalinteger返回的能力结果数量。
resultsarray能力结果；每一项使用与 Discover 相同的能力结果字段。
elapsed_time_msnumber可用时返回 Inspect 耗时，单位毫秒。
remaining_creditsnumber/null可用时返回账户剩余积分。
error_messagestring/null业务失败时的错误说明。

错误响应

超时：

json
{
  "error": "Request timeout",
  "remaining_credits": 995
}

代理异常：

json
{
  "error": "Tools by-ids failed: upstream service unavailable",
  "remaining_credits": 995
}

3. 预检能力

text
POST /tools/probe?tool_id={tool_id}

Probe 是可选预检：它会在不执行能力、不消耗积分的前提下校验候选参数或返回当前报价。仅在任务需要校验或报价时使用，无需把它作为 Call 的固定前置步骤。响应中的 recovery 会给出缺失字段、安全修复、是否可重试、下一步动作和 Provider 回退建议。非关键元数据缺失只会降低置信度或产生 warning，不会隐藏能力；明确的安全、身份、法律、地域、预算或不可逆执行冲突仍会阻止对应动作。

请求

json
{
  "parameters": {
    "q": "北京"
  },
  "checks": ["schema", "quote"],
  "live_budget": "none"
}

请使用 Discover 或 Inspect 选中的原始 tool_id。仅做校验时，应保持 live_budget 为 none。

成功响应（验证字段从略）

json
{
  "schema": {
    "valid": true
  },
  "quote": {
    "estimate_credits": 5,
    "currency": "credits",
    "exact": true,
    "basis": "per_call"
  },
  "recovery": {
    "missing_fields": [],
    "safe_fixes": [],
    "retryable": true,
    "next_action": "execute",
    "provider_fallback": false
  }
}

recovery.missing_fields 只列出缺失或无效的调用参数。目录验证证据缺口保留在 verification.quality_issues 中，本身不要求智能体在 Call 前再执行额外步骤。

输入无效时可返回 400，能力不存在时返回 404，触发限流时返回 429，Probe 服务不可用或超时时返回 502/504。精确 schema 和全部响应请查看 Probe 聚焦参考页。

4. 调用能力

text
POST /tools/execute?tool_id={tool_id}

tool_id 可以放在 query 参数或 JSON body 中。推荐使用 query 参数，便于日志追踪。

请求

json
{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "gpt-4o",
  "parameters": {
    "q": "北京"
  },
  "max_response_size": 20480
}
字段类型必填说明
tool_idstring整体必填要执行的工具唯一标识符；可作为 query 参数或 JSON body 字段提供。
search_idstring推荐返回所选工具的 search id
session_idstring否追踪和计费上下文 ID；省略时服务可能使用 execution id
modelstring智能体推荐选择工具或生成参数的不含空白或控制字符的非空模型标识，最长 128 个字符，例如 gpt-4.1、deepseek-v4-pro 或 claude-sonnet-4
parametersobject是根据 Discover 或 Inspect 返回的所选能力当前契约构造的能力专属参数
max_response_sizeinteger否自动内联阈值，按 result.data JSON 序列化后的 UTF-8 字节数计算；默认 20480，-1 表示完整内联。显式 full 优先于有限值；summary 不受其影响。
respond_withstring否交付模式：省略时使用兼容自动交付；显式 full 强制完整内联 result.data；fields:<JSONPath,...> 先投影再应用大小阈值；summary 返回统计或保留 data/溢出回退。

工具参数或投影无效时返回 HTTP 422，并通过 details 给出字段级错误；鉴权失败返回统一 API 错误对象，不再伪装成成功 Call 或空 Search 结果。

交付优先级：

respond_withmax_response_size交付形态
省略省略 / 正整数未超默认值 / 指定值时内联；超限时返回截断预览和完整内容 URL
省略-1完整内联数据
full任意值或省略完整内联 result.data；有限大小值不会使其降级
fields:...省略 / 正整数 / -1先投影，再应用默认 / 指定 / 不限大小的内联规则
summary任意值或省略摘要、无损数据或完整溢出回退

如果显式 full 超过平台硬安全上限，请求会以 error_code: response_too_large 失败，不会静默改成截断信封。二进制附件继续使用独立附件交付契约，不会隐式 base64 编码进 JSON。

只从选中的工具构造 parameters：

  • 使用选中结果的 params 字段作为必填 schema。
  • 遵守 required 和 enum 字段。
  • 对于 CAP 能力，遵守 one_of_required；每个分组表示该组字段至少传一个。
  • examples.sample_parameters 只作为结构和典型值参考。
  • 如果参数错误看起来属于另一个 provider 或另一个工具，请重新 search 或 inspect 当前 tool_id；这通常意味着客户端混用了两个工具的 schema。

成功响应

json
{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "局部多云"
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.211,
  "elapsed_time_ms": 211,
  "billing": {
    "summary": "每次成功请求 5 积分",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

响应字段

字段类型说明
execution_idstring本次执行的唯一 id。请将示例中的 exec_... 替换为你自己响应返回的 id。
resultobject工具执行结果；兼容自动交付和 fields 投影可能使用下方的超限结构；显式 full 成功时始终包含 result.data。
successboolean工具执行是否成功。不要只根据此字段判断最终是否扣费。
error_messagestring/nullsuccess=false 时的错误说明。
execution_timenumber执行耗时，单位秒；这是 execute 响应的兼容字段。
elapsed_time_msnumber可用时返回执行耗时，单位毫秒。
billingobject可用时返回紧凑的预结算账单。
costnumber可用时返回旧版/预结算成本信号。
remaining_creditsnumber/null可用时返回账户剩余积分。

摘要模式至少保留一种可用载荷：summary 对象、无损 data，或同时存在的 truncated_content 与 full_content_file_url。这些字段可以共存；仅凭模式不能保证摘要或下载链接存在。先检查 success，再检查字段是否存在；失败的摘要调用保留空 data 对象。 可选元数据包括 content_schema 和 message。签名链接必须按返回的原样使用。

示例：空结果，不扣费

部分 provider 会返回合法响应，但没有可用结果。这种情况下 success 可以是 false，错误信息应提示用户当前参数没有结果，最终调用审计通常应归类为 failed_not_charged。

json
{
  "execution_id": "exec_01HZX9EMPTY",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "The provider returned no results for the current parameters. Try different parameters.",
  "execution_time": 0.184,
  "elapsed_time_ms": 184,
  "billing": {
    "summary": "不扣费：提供商未返回可用结果",
    "list_amount_credits": 0
  },
  "cost": 0,
  "remaining_credits": 990
}

错误响应

缺少 tool_id：

json
{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Missing required parameter: tool_id. Provide it as query (?tool_id=xxx) or in JSON body.",
  "execution_time": 0.01
}

积分不足：

json
{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Insufficient credits",
  "execution_time": 0.01,
  "remaining_credits": 0
}

上游工具失败：

json
{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Execute API error: HTTP 502",
  "execution_time": 0.211,
  "remaining_credits": 990
}

错误排查表

错误类别典型现象需要检查推荐处理
tool_id 格式错误请求在进入 provider 前被拒绝。是否完整复制了 Discover 或 Inspect 返回的 tool_id？使用 API 返回的原始 tool_id，不要缩写、归一化或猜测。
tool_id 不存在服务无法解析所选能力。工具是否来自旧缓存、已下线或在当前区域不可用？重新 Discover，并执行当前返回的工具。
参数错误缺少必填字段、枚举值错误、类型错误、日期范围错误或代码格式错误。请求体是否符合所选工具当前 params？基于所选结果或 Inspect 响应重新生成 parameters。
schema 错配参数看起来属于另一个 provider 或另一个工具。智能体是否选择了一个 tool_id，却填了另一条 search 结果的参数？把 search_id、选中结果和参数 schema 放在同一个上下文对象中传递。
权限或区域错误provider 执行前出现 auth、OAuth 或区域限制。账号是否授权？客户端是否使用正确区域的 API base URL？让用户完成 OAuth、切换区域，或选择另一个返回的工具。
第三方接口错误参数已接受，但上游返回 HTTP/provider 错误。查看 error_message；需要结构化 reason_code 时查询调用审计。视情况重试、选择其他 provider，或带 execution_id 联系支持。

联系支持时，请提供 execution_id、search_id、session_id、tool_id；如果是智能体客户端，也提供 model。这些字段可以帮助区分问题来自搜索排序、工具选择、参数生成、本地校验，还是第三方 provider。

核对结果未知的 Call

text
GET /tools/executions/by-idempotency-key?key={original_idempotency_key}

付费 Call 的 HTTP 响应丢失后，请使用原始 Idempotency-Key 查询这个只读端点。该端点不会授权新的 provider 执行。如果所选结算路径无法提供持久恢复能力，原始 Call 会在 provider 请求发出前返回 409 idempotency_key_unsupported。响应使用标准 API envelope；data.status 为 pending、completed 或 unavailable。completed 时，data.response 包含可恢复的原始 Call 响应；unavailable 表示已确认该执行存在，但无法安全重建完整结果，例如长结果的短期下载链接已经失效。

长响应

省略 respond_with 或使用 fields:... 投影时，payload 超过有效 max_response_size 后，result 可能用下方超限字段替代 data。显式 respond_with: "full" 的成功响应绝不会使用此结构。

json
{
  "result": {
    "message": "Result content is too long. Use truncated_content or download full_content_file_url.",
    "full_content_file_url": "https://oss.qveris.ai/tool_result_cache/result.json?Expires=1700007200&Signature=example",
    "truncated_content": "{\"query\":\"evolution\",\"total_results\":890994",
    "content_schema": {
      "type": "object"
    }
  }
}
字段说明
truncated_content工具响应的前几个字节
full_content_file_url用于从 QVeris 对象存储直接下载完整内容的临时 HTTPS 签名 URL。请原样使用，不要改写，也不要假设它与 API 同域；链接会过期。
message适合给 LLM 读取的截断说明
content_schema完整内容的 JSON schema（如果可用）

5. 调用审计 — 最终请求状态

调用审计用于回答：“这次请求是否成功？”、“失败请求是否扣费？”、“哪一次执行需要客服复核？”。Agent、CLI、MCP 客户端应优先使用精确过滤或 summary=true，不要把全量历史直接输出给 LLM。

端点

text
GET /auth/usage/history/v2

请求头

请求头必填说明
Authorization是Bearer API key

查询参数

参数类型必填说明默认值 / 范围
start_datestring否审计窗口开始时间。支持 YYYY-MM-DD 或 ISO-8601 datetime。-
end_datestring否审计窗口结束时间。YYYY-MM-DD 会扩展到当天结束。-
event_typestring否精确事件类型：search、search_by_ids、tool_execute、capabilities_query、model_call。-
kindstring否高层分组。discover 对应 search + search_by_ids；call 对应 tool_execute + capabilities_query；model 对应 model_call。-
successboolean否使用事件记录的成功标记。-
billable_successboolean否计费侧成功标记；某些 provider/outcome 边界场景可能与 success 不同。-
outcomestring否execution_outcome.outcome 的标准化结果过滤。-
reason_codestring否标准化执行原因，例如 provider 或参数校验原因。-
has_execution_outcomeboolean否true 只返回有结构化 execution outcome 的事件；false 只返回没有该结构的事件。-
charge_outcomestring否最终扣费分类：charged、included、failed_not_charged、failed_charged_review。-
anomalystring否审计异常过滤：failed_charged_review、missing_ledger_link、missing_billing_snapshot。-
search_idstring否聚焦到某次 Discover 相关事件。-
execution_idstring否聚焦到某次 Call 执行；最适合回答“这次调用是否扣费”。-
min_creditsnumber否最小有效结算/请求积分。必须 >= 0。-
max_creditsnumber否最大有效结算/请求积分。必须 >= 0。-
pageinteger否页码。默认 1，最小 1
page_sizeinteger否未传 limit 时的每页数量。默认 50，范围 1-50000
summaryboolean否返回服务端聚合和高信号样本。若没有传日期，summary 默认最近 24 小时。默认 false
bucketstring否summary 时间粒度。hour、day、week；超过 3 天自动用 day，否则用 hour
limitinteger否覆盖返回样本数量，并限制在适合上下文的上限内。Agent/CLI/MCP 场景推荐使用。1-50；summary 默认样本 10

charge_outcome 取值

值含义
charged有效成功标记为 true，且最终/有效积分金额大于 0。
included有效成功标记为 true，且最终/有效积分金额为 0，例如免费额度或策略豁免。
failed_not_charged有效成功标记为 false，且最终/有效积分金额为 0。
failed_charged_review有效成功标记为 false，但最终/有效积分金额大于 0；应作为客服/复核场景处理。

常见 reason_code

reason_code 足够稳定，可用于自动化、过滤和客服排查。面向用户的文案可能调整；机器客户端应优先依赖 code。

Reason code典型扣费结果面向用户的含义
result.validcharged 或 includedprovider 返回了可用数据。
result.partial_successcharged、included 或 failed_not_chargedprovider 返回了部分数据；需要结合结果和账单判断。
result.emptyfailed_not_chargedprovider 有响应，但没有可用结果数据。
provider.errorfailed_not_chargedprovider 返回错误。
provider.http_errorfailed_not_chargedprovider 返回非成功 HTTP 响应。
provider.rate_limitedfailed_not_charged上游 provider 对请求限流。
provider.auth_or_permissionfailed_not_charged上游 provider 拒绝认证或权限。
transport.timeoutfailed_not_chargedQVeris 在超时前没有收到 provider 响应。
transport.no_responsefailed_not_chargedQVeris 未能获取 provider 响应。
transport.execution_failedfailed_not_charged执行链路在拿到可计费 provider 结果前失败。
validation_errorfailed_not_charged请求参数无效或不完整。
tool_unavailablefailed_not_charged所选能力不可用。
region_restrictedfailed_not_charged所选能力在当前区域不可用。
oauth_signin_requiredfailed_not_charged能力执行前需要先完成 OAuth 登录。

示例：按 execution_id 查询一次执行

bash
curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
  -H "Authorization: Bearer $QVERIS_API_KEY"
json
{
  "status": "success",
  "message": "Usage events retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "evt_01HZX9R31GH2R",
        "event_type": "tool_execute",
        "source_system": "qveris_website",
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "session_id": "sess_7Q9m",
        "search_id": "srch_01HZX9QK7J3M9T",
        "execution_id": "exec_01HZX9R2R4S2E",
        "tool_id": "openweathermap.weather.execute.v1",
        "success": true,
        "charge_outcome": "charged",
        "reason_code": "result.valid",
        "duration_ms": 211,
        "billing_snapshot_status": "upstream_provided",
        "billing_rule_snapshot": {
          "unit": "request",
          "amount_credits": 5
        },
        "pre_settlement_bill": {
          "summary": "每次成功请求 5 积分",
          "list_amount_credits": 5
        },
        "settlement_result": {
          "settled_amount_credits": 5
        },
        "pre_settlement_amount_credits": 5,
        "settled_amount_credits": 5,
        "actual_amount_credits": 5,
        "credits_ledger_entry_id": "led_01HZX9R39K6QZ",
        "display_target": "openweathermap.weather.execute.v1",
        "billing_summary": "每次成功请求 5 积分",
        "created_at": "2026-05-16T08:30:12Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50,
    "summary": null
  }
}

示例：适合 Agent 上下文的聚合摘要

bash
curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?summary=true&bucket=day&kind=call&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
  -H "Authorization: Bearer $QVERIS_API_KEY"
json
{
  "status": "success",
  "message": "Usage events retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "evt_01HZX9R31GH2R",
        "event_type": "tool_execute",
        "execution_id": "exec_01HZX9R2R4S2E",
        "tool_id": "openweathermap.weather.execute.v1",
        "success": true,
        "charge_outcome": "charged",
        "settled_amount_credits": 5,
        "created_at": "2026-05-16T08:30:12Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 5,
    "summary": {
      "start_date": "2026-05-01T00:00:00Z",
      "end_date": "2026-05-16T23:59:59.999999Z",
      "bucket": "day",
      "total_count": 42,
      "success_count": 40,
      "failure_count": 2,
      "charge_outcome_counts": {
        "charged": 35,
        "included": 5,
        "failed_not_charged": 2,
        "failed_charged_review": 0
      },
      "pre_settlement_credits": 210,
      "settled_credits": 175,
      "max_charge_items": [],
      "buckets": [
        {
          "bucket_start": "2026-05-16T00:00:00Z",
          "total_count": 8,
          "success_count": 8,
          "failure_count": 0,
          "charged_count": 7,
          "included_count": 1,
          "failed_not_charged_count": 0,
          "failed_charged_review_count": 0,
          "pre_settlement_credits": 40,
          "settled_credits": 35
        }
      ]
    }
  }
}

响应字段

顶层响应使用标准 APIResponse 包装。

字段类型说明
statusstringsuccess 或 failure。
messagestring服务端可读消息。
status_codeinteger应用状态码。成功为 0；校验失败为负数。
data.itemsarray按时间倒序返回的 usage events。
data.totalinteger匹配过滤条件的总数。
data.pageinteger当前页码。
data.page_sizeinteger实际返回样本数。若传 limit，它会覆盖 page_size 并被限制到 50。
data.summaryobject/nullsummary=true 时返回聚合摘要，否则为 null。

重要 data.items[] 字段：

字段说明
event_type标准事件类型。search = Discover，search_by_ids = Inspect，tool_execute / capabilities_query = Call，model_call = 模型调用。
search_id / execution_idDiscover 或 Call 流程的关联 id。
success使用事件记录的成功标记。
charge_outcome面向用户的最终扣费分类。不要只根据 success 猜测是否扣费。
error_message可用时返回错误详情。
duration_ms请求耗时，单位毫秒。
request_payload / response_payload_summary审计用请求/响应摘要。Agent 客户端默认不应直接输出这些字段。
execution_outcome 及 outcome 字段可用时返回结构化 provider/result outcome。
billing_rule_snapshot请求当时捕获的计费规则。
pre_settlement_bill最终账本结算前的预结算账单。
settlement_result可用时返回最终结算结果。
requested_amount_credits / actual_amount_credits请求金额与最终/有效金额。
credits_ledger_entry_id该 usage event 对应的最终账本行 id。
display_target / billing_summary适合 UI 展示的目标和计费摘要。

错误响应

日期或 bucket 无效：

json
{
  "status": "failure",
  "message": "Invalid start_date format. Use YYYY-MM-DD or ISO-8601 datetime",
  "status_code": -7,
  "data": null
}

积分区间无效：

json
{
  "status": "failure",
  "message": "min_credits cannot be greater than max_credits",
  "status_code": -7,
  "data": null
}

6. Credits 账本 — 最终余额变动

Credits 账本用于解释最终账户余额。调用审计描述“请求发生了什么”；账本描述“余额如何不可变地变动”。一次已扣费的 Call 通常应该同时存在 charge_outcome=charged 的 usage event 和关联的账本行。

端点

text
GET /auth/credits/ledger

请求头

请求头必填说明
Authorization是Bearer API key

查询参数

参数类型必填说明默认值 / 范围
start_datestring否账本窗口开始时间。支持 YYYY-MM-DD 或 ISO-8601 datetime。-
end_datestring否账本窗口结束时间。YYYY-MM-DD 会扩展到当天结束。-
entry_typestring否精确账本事件类型，例如 consume_tool_execute。-
scopestring否预设事件类型组。account_history 包含 grant_payment_recharge、consume_tool_search、consume_tool_execute、consume_model_call。-
directionstring否余额方向。consume 返回负数消耗；grant 返回正数发放；any 返回两者。默认 any；允许 consume、grant、any
min_creditsnumber否最小绝对积分金额。例如 min_credits=5 同时匹配 -5 和 +5。必须 >= 0。-
max_creditsnumber否最大绝对积分金额。必须 >= 0。-
pageinteger否页码。默认 1，最小 1
page_sizeinteger否未传 limit 时的每页数量。默认 50，范围 1-500
summaryboolean否返回聚合余额变动摘要。若没有传日期，summary 默认最近 24 小时。默认 false
bucketstring否summary 时间粒度。hour、day、week；超过 3 天自动用 day，否则用 hour
limitinteger否覆盖返回样本数量和 summary 最大金额样本，适合 Agent/CLI/MCP 使用。1-50；summary 默认样本 10

常见 entry_type

值含义
grant_payment_recharge充值/支付发放积分。
grant_welcome_bonus新用户或活动赠送积分。
grant_invitation_reward邀请/推荐奖励积分。
consume_tool_searchDiscover 消耗积分；仅在部署策略对搜索计费时出现。
consume_tool_execute能力 Call 消耗积分。
consume_model_call模型调用消耗积分。
consume_payment_refund退款相关的积分变动。

示例：查询最近的 Call 扣费

bash
curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&page=1&page_size=10" \
  -H "Authorization: Bearer $QVERIS_API_KEY"
json
{
  "status": "success",
  "message": "Credits ledger retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "led_01HZX9R39K6QZ",
        "entry_type": "consume_tool_execute",
        "amount_credits": -5,
        "source_system": "qveris_website",
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "execution_id": "exec_01HZX9R2R4S2E",
        "pre_settlement_bill": {
          "execution_id": "exec_01HZX9R2R4S2E",
          "summary": "每次成功请求 5 积分",
          "list_amount_credits": 5
        },
        "settlement_result": {
          "settled_amount_credits": 5
        },
        "balance_before": {
          "total_available_credits": 995
        },
        "balance_after": {
          "total_available_credits": 990
        },
        "description": "Tool execution charge",
        "created_at": "2026-05-16T08:30:13Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "summary": null
  }
}

示例：聚合余额变动

bash
curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_history&direction=any&bucket=day&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
  -H "Authorization: Bearer $QVERIS_API_KEY"
json
{
  "status": "success",
  "message": "Credits ledger retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "led_01HZX9R39K6QZ",
        "entry_type": "consume_tool_execute",
        "amount_credits": -5,
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "execution_id": "exec_01HZX9R2R4S2E",
        "created_at": "2026-05-16T08:30:13Z"
      }
    ],
    "total": 18,
    "page": 1,
    "page_size": 5,
    "summary": {
      "start_date": "2026-05-01T00:00:00",
      "end_date": "2026-05-16T23:59:59.999999",
      "bucket": "day",
      "total_entries": 18,
      "consume_count": 14,
      "grant_count": 4,
      "consumed_credits": 175,
      "granted_credits": 1000,
      "net_amount_credits": 825,
      "max_amount_items": [],
      "buckets": [
        {
          "bucket_start": "2026-05-16T00:00:00",
          "entry_count": 3,
          "consume_count": 3,
          "grant_count": 0,
          "consumed_credits": 15,
          "granted_credits": 0,
          "net_amount_credits": -15
        }
      ]
    }
  }
}

响应字段

字段类型说明
data.itemsarray按时间倒序返回的账本行。
data.totalinteger匹配过滤条件的总数。
data.page / data.page_sizeinteger当前页码和实际返回样本数。
data.summaryobject/nullsummary=true 时返回聚合余额摘要，否则为 null。

重要 data.items[] 字段：

字段说明
entry_type不可变账本事件类型。
amount_credits带符号的余额变动。负数表示消耗，正数表示发放。
source_system创建账本行的系统。
source_ref_type / source_ref_id后端审计用来源行引用。
execution_id/tools/execute 返回的 Call 执行 id；用户对账时使用这个字段。可用时会出现在 Call 账本行。
pre_settlement_bill最终结算前的计费快照。
settlement_result最终结算结果。
balance_before / balance_after可用时返回本次变动前后的余额快照。
ledger_metadata用于审计/调试的附加元数据。
description人类可读的账本说明。
created_at创建时间。

Summary 字段：

字段说明
total_entries匹配账本行总数。
consume_count / grant_count负数消耗和正数发放的条目数量。
consumed_credits / granted_credits消耗和发放的绝对值总量。
net_amount_credits带符号净额；发放为正，消耗为负。
max_amount_items绝对金额最大的高信号样本，受 limit 限制。
buckets按时间粒度聚合的时间序列，适合图表或 Agent 摘要。

错误响应

direction 无效：

json
{
  "status": "failure",
  "message": "Invalid direction. Use consume, grant, or any",
  "status_code": -7,
  "data": null
}

积分区间无效：

json
{
  "status": "failure",
  "message": "min_credits must be greater than or equal to 0",
  "status_code": -7,
  "data": null
}

端到端 smoke checklist

  1. 创建新的 session_id。
  2. 执行 Discover 并保存 search_id。
  3. Inspect 所选 tool_id，确认必填 params 和调用前成本字段。
  4. 使用有效 parameters 调用，并保存 execution_id。
  5. 用 execution_id 查询调用历史。
  6. 查询积分账本，确认最终余额变动与调用历史结果一致。

OpenAPI

QVeris 公开 OpenAPI 提供稳定的 JSON 和 YAML 地址，并为固定版本的集成提供 JSON 与 YAML 地址。文档包含所有已发布操作的请求体、响应结构与示例；旧服务兼容样例仍见投影 fixtures。

这个页面对你有帮助吗？