调用能力

POST /tools/execute

调用能力

REST API 概览 · OpenAPI JSON · OpenAPI YAML

接口契约

稳定性	认证	费用	Operation ID
已发布	Bearer API 密钥	取决于所选能力的 billing_rule	`execute_api_v1_tools_execute_post`

参数

名称	位置	必填	类型	说明
`tool_id`	query	否	`string \| null`	Tool ID (optional if provided in request body)
`X-QVeris-Cache-Mode`	header	否	`string \| null`	缓存策略：default（默认）或 bypass（跳过provider缓存）
`Idempotency-Key`	header	否	`string \| null`	Caller-generated key used to reconcile uncertain execution outcomes

请求体

Schema: PublicExecuteToolRequest

名称	必填	类型	说明
`tool_id`	否	`string`	Capability id. Optional when supplied as the `tool_id` query parameter.
`search_id`	否	`string`	Search id that returned the selected capability.
`session_id`	否	`string`	Optional tracking and pricing-context identifier. If omitted, the service may use the execution id.
`sub_user_id`	否	`string`	Optional sub-user identity used consistently for provider OAuth and execution.
`model`	否	`string`	Model that selected the capability or generated its parameters.
`parameters`	是	`object`	Capability-specific parameters validated by the selected tool schema.
`max_response_size`	否	`object`	Automatic inline-delivery limit, measured as the UTF-8 byte length of serialized `result.data`. The default is 20480 when omitted; use -1 for unlimited inline delivery. An explicit `respond_with: full` takes precedence over any finite value. Summary mode may preserve lossless data or a complete overflow fallback.
`respond_with`	否	`string`	Result delivery mode. When omitted, the compatibility mode uses `max_response_size` (default 20480) and may return a truncated preview plus `full_content_file_url`. Explicit `full` forces the complete `result.data` inline and takes precedence over a finite `max_response_size`; if the platform hard safety limit is exceeded, the call fails with `error_code: response_too_large` instead of silently degrading. `fields:<JSONPath,...>` returns only the selected fields — JSONPath expressions are rooted at `result.data`, comma-separated, and at least one non-empty expression is required. `summary` normally returns statistics with optional schema and download URL. It preserves lossless `data` or a `truncated_content` plus `full_content_file_url` fallback when available. Check success and field availability; the mode alone does not guarantee statistics or a URL.

可运行示例

bash

curl --request POST \
  --url "https://qveris.ai/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'

typescript

const response = await fetch("https://qveris.ai/api/v1/tools/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.QVERIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}),
})

if (!response.ok) throw new Error(`QVeris request failed: ${response.status}`)
console.log(await response.json())

python

import json
import os
import requests

response = requests.request(
    "POST",
    "https://qveris.ai/api/v1/tools/execute",
    headers={"Authorization": f"Bearer {os.environ['QVERIS_API_KEY']}"},
    json=json.loads(r'''{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'''),
    timeout=30,
)
response.raise_for_status()
print(response.json())

响应

状态码	含义	Schema
`200`	Successful Response	`PublicExecuteToolResponse`
`401`	Unauthorized	`PublicApiError`
`402`	Insufficient credits	`PublicExecuteToolResponse`
`409`	Idempotency key already exists, conflicts, or cannot be honored by the selected settlement path	`unknown`
`413`	Explicit full response exceeds the platform safety limit	`PublicExecuteToolResponse`
`422`	Validation Error	`PublicExecuteToolResponse`
`429`	Too Many Requests	`PublicApiError`
`502`	Upstream result delivery violated the public contract	`PublicExecuteToolResponse`

成功响应示例

json

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "partly cloudy"
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.211,
  "billing": {
    "summary": "5 credits per successful request",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

精确契约

稳定版 JSON: OpenAPI JSON
稳定版 YAML: OpenAPI YAML
版本化 JSON: OpenAPI v1 JSON
版本化 YAML: OpenAPI v1 YAML

调用能力

接口契约

参数

请求体

可运行示例

响应

成功响应示例

精确契约

相关操作