调用能力

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)

请求体

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.
`parameters`	是	`object`	Capability-specific parameters validated by the selected tool schema.
`max_response_size`	否	`integer`	Maximum response payload bytes before truncation. Use -1 for no limit.
`respond_with`	否	`string`	Server-side result projection. `full` (default) returns the complete result, byte-identical to previous releases. `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` returns the response schema, size/row statistics, and a `full_content_file_url` for the complete payload.

可运行示例

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",
  "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",
  "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",
  "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`
`422`	Validation Error	`PublicExecuteToolResponse`
`429`	Too Many Requests	`PublicApiError`

成功响应示例

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

调用能力

接口契约

参数

请求体

可运行示例

响应

成功响应示例

精确契约

相关操作