search - 搜索接口 按 Token 计费

搜索接口用于根据自然语言查询搜索可用的工具。基于语义匹配返回最相关的工具列表，包含工具的详细信息和参数说明。

接口地址

POST https://api.jisuapi.com/agent/search

请求参数

请求头

响应格式

成功响应（status: 0）

{
  "status": 0,
  "msg": "ok",
  "result": {
    "search_id": "sch_20260603_120001_xxx",
    "query": "查询手机号归属地",
    "total": 2,
    "tools": [
      {
        "tool_id": "shouji_query",
        "name": "手机号码归属地查询",
        "description": "查询手机号码的归属地、运营商等信息",
        "category": "生活",
        "price_info": {
          "is_free": true,
          "free_quota": 100,
          "price_per_call": 0.0
        },
        "parameters": {
          "mobile": {
            "type": "string",
            "required": true,
            "description": "11位手机号码"
          }
        },
        "example": {
          "mobile": "13800138000"
        },
        "match_score": 0.95
      }
    ]
  },
  "request_id": "req_..."
}

失败响应

{
  "status": 303,
  "msg": "搜索查询为空",
  "result": null
}

错误码

响应字段说明

tool 对象

请求示例

基础搜索

curl -X POST "https://api.jisuapi.com/agent/search" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "查询手机号归属地"
  }'

限制返回数量

curl -X POST "https://api.jisuapi.com/agent/search" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "天气预报",
    "limit": 3
  }'

分类筛选

curl -X POST "https://api.jisuapi.com/agent/search" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "股票",
    "category": "金融",
    "limit": 5
  }'

Python 示例

import requests

url = "https://api.jisuapi.com/agent/search"
headers = {
    "Authorization": "Bearer 你的APPKEY",
    "Content-Type": "application/json"
}
data = {
    "query": "查询手机号归属地",
    "limit": 3
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["status"] == 0:
    tools = result["result"]["tools"]
    print(f"找到 {len(tools)} 个工具:")
    for tool in tools:
        print(f"- {tool['name']} ({tool['tool_id']})")
        print(f"  描述: {tool['description']}")
        print(f"  匹配度: {tool['match_score']:.2f}")
else:
    print(f"搜索失败: {result['msg']}")

最佳实践

• 自然语言查询：使用自然、口语化的查询，例如"查询天气"比"weather api"效果更好
• 保存 search_id：返回的 search_id 可传递给 execute 接口，用于追踪完整调用链
• 检查匹配度：优先使用 match_score 高的工具，通常 > 0.7 的结果比较可靠
• 查看参数说明：在调用 execute 前仔细检查 parameters 字段了解所需参数
• 分类筛选：当搜索结果过多时，使用 category 参数缩小范围

搜索技巧

精确搜索

包含关键词和具体需求，例如：

• ✓ "查询北京的天气预报" - 明确地点和需求
• ✓ "手机号13800138000的归属地" - 包含具体数据
• ✗ "天气" - 过于笼统

多关键词组合

使用多个相关关键词提高准确度：

• "身份证 实名认证 验证"
• "股票 实时行情 查询"
• "IP地址 归属地 定位"

常见问题

Q: 搜索接口收费吗？

A: 完全免费，不消耗任何额度。

Q: 如何提高搜索准确度？

A: 使用更具体的描述，包含关键词和使用场景。例如用"查询手机号归属地"代替"手机"。

Q: match_score 多少算准确？

A: 通常 > 0.7 表示较好匹配，> 0.9 表示非常准确。建议提示用户确认或展示多个选项。

Q: 没有找到想要的工具怎么办？

A: 尝试换用不同的关键词或更详细的描述。也可以访问 Agent 可用接口列表 浏览所有工具。