Trinity Web Search

向平台提交一次联网检索，返回结构化结果（results[]）与可选简短作答（answer）。模型 ID 固定为 trinity:web_search，不支持在请求体中更换模型。

适用于需要实时、可批量读取网页结果的场景。若只需在对话中附带网络信息，可改用 创建对话补全，在 tools 中声明 web_search。

---

Endpoint

Method	URL	说明
POST	{TRINITY_BASE_URL}/web_search	提交一次检索

---

Base URL

项	值
Base URL	https://api.trinitydesk.ai/v1
协议	HTTPS

export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

---

Headers

Header	必填	说明
Authorization	是	Bearer <TRINITY_API_KEY>
Content-Type	是	application/json

---

请求体字段

字段	类型	必填	说明
query	string	是	检索问句；最长 2000 字符
max_uses	integer	否	服务器最多执行检索的次数，默认 1；取值范围 1~3。超出范围时按边界收敛
include_answer	boolean	否	是否返回简短作答，默认 true；false 时 answer 返回 null
user	string	否	可选的终端用户标签，用于日志追溯

此接口不支持 model 字段；模型固定为 trinity:web_search。价格见 获取价目（?model=trinity:web_search）。

---

请求示例

curl -sS "${TRINITY_BASE_URL}/web_search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "query": "What is the capital of France?",
    "max_uses": 1,
    "include_answer": true
  }'

---

返回字段

字段	类型	说明
id	string	本次检索结果 ID，形如 wsrch_…
object	string	固定为 "web_search.result"
model	string	固定为 "trinity:web_search"
created	integer	Unix 时间戳（秒）
query	string	原始检索问句
answer	string / null	简短作答；include_answer=false 时为 null
results	array	结构化结果列表，见下节
usage	object	token 用量

results[]

字段	类型	说明
title	string / null	结果标题
url	string	结果链接
snippet	string / null	结果摘要；无摘要时为 null

usage

字段	类型	说明
input_tokens	integer	输入 token 数
cache_read_input_tokens	integer	缓存命中的输入 token 数
cache_creation_input_tokens	integer	写缓存产生的输入 token 数
output_tokens	integer	输出 token 数
web_search_requests	integer	本次实际执行的检索次数

---

返回示例

{
  "id": "wsrch_abcd1234",
  "object": "web_search.result",
  "model": "trinity:web_search",
  "created": 1730000000,
  "query": "What is the capital of France?",
  "answer": "Paris is the capital of France.",
  "results": [
    {
      "title": "France - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/France",
      "snippet": "France, officially the French Republic, is a country whose capital is Paris."
    },
    {
      "title": "Visit Paris",
      "url": "https://paris.example.com",
      "snippet": null
    }
  ],
  "usage": {
    "input_tokens": 31047,
    "cache_read_input_tokens": 384,
    "cache_creation_input_tokens": 0,
    "output_tokens": 141,
    "web_search_requests": 1
  }
}

---

错误码

HTTP	error.code	场景
400	invalid_request	query 缺失或超长
401	authentication_error	API Key 缺失或无效
402	insufficient_balance	余额不足
404	—	模型未配置或不可用
429	rate_limit_exceeded	速率限制
502	upstream_search_unavailable	上游未返回服务器检索结果

完整错误码见 错误与调试。

---

Python 示例

import os
import requests

r = requests.post(
    f"{os.environ['TRINITY_BASE_URL']}/web_search",
    headers={
        "Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "query": "What is the capital of France?",
        "max_uses": 1,
        "include_answer": True,
    },
    timeout=60,
)
r.raise_for_status()
result = r.json()
print(f"answer: {result.get('answer')}")
for row in result.get("results", []):
    print(f"- {row.get('title')}: {row.get('url')}")
print(f"usage: {result.get('usage')}")

---

相关

• 获取价目
• 创建对话补全
• 创建 Responses
• 错误与调试