QVeris 文档

QVeris 是面向智能体的能力路由网络。客户端可以用自然语言发现能力，检查候选能力的参数 schema 与成本信号，然后用结构化参数调用选中的能力。

五分钟完成首次调用

这条路径使用公开 REST API，因为 SDK 与 MCP 集成都映射到同一条发现 -> 检查 -> 调用流程。

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

1. 创建 API key

在控制台/API 密钥页面创建密钥，并且不要把它提交到代码仓库。

export QVERIS_API_KEY="qv_your_key"
export QVERIS_BASE_URL="https://qveris.cn/api/v1"
export QVERIS_SESSION_ID="quickstart-$(date +%s)"

2. 发现能力

Discover 免费。响应会返回 search_id 和排序后的候选能力。

curl -sS "$QVERIS_BASE_URL/search" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "城市天气预报 API",
    "limit": 3,
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

示例响应：

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "provider_name": "OpenWeatherMap",
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": { "unit": "request", "amount_credits": 5 },
      "stats": { "avg_execution_time_ms": 210.7, "success_rate": 0.982 }
    }
  ],
  "remaining_credits": 995
}

3. 检查候选能力

Inspect 也免费。在调用前，用它查看完整参数、示例、质量指标和最新 billing_rule。

curl -sS "$QVERIS_BASE_URL/tools/by-ids" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["openweathermap.weather.execute.v1"],
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

4. 调用能力

Call 可能消耗积分。使用 Discover 或 Inspect 返回的 tool_id。

curl -sS "$QVERIS_BASE_URL/tools/execute?tool_id=openweathermap.weather.execute.v1" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'",
    "parameters": { "city": "北京", "units": "metric" },
    "max_response_size": 20480
  }'

示例响应：

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

5. 验证最终结算

Call 响应里的 billing 和 cost 是预结算信号。最终状态以调用历史和积分账本为准。

curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&limit=10" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

成本语义

Discover 和 Inspect 免费。它们可能返回 expected_cost、cost 或 billing_rule，用于在 Call 之前估算成本。

Call 按所选能力的 billing_rule 计费。Call 响应可能包含简要 billing 和 cost，但调用历史与积分账本才是最终结算依据。

`session_id` 语义

建议在一次用户任务或会话中使用稳定的 session_id。目前它用于追踪、分析和计费上下文；它不是缓存合同，也不承诺 session_cache_hit。如果未来 API 增加显式缓存字段，会单独文档化。

集成方式

REST API：REST API 参考
实践指南：常见 API 调用示例
CLI：CLI 文档
MCP：MCP Server 文档
Python SDK：Python SDK