快速入门

API 参考

其他资源

首页 / Agent / 文档 / HTTP 网关 API

HTTP 网关 API

通过 HTTP 网关将 jisuapi Agent 服务集成到自研 Agent、Python/Java/Go 应用中。

认证方式

所有 API 请求需要在 HTTP Header 中携带 APPKEY：

Authorization: Bearer 你的APPKEY

认证示例

curl -X POST "https://api.jisuapi.com/agent/search" \
  -H "Authorization: Bearer your_appkey_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"查询天气"}'

安全提示：请勿在前端代码中暴露 APPKEY，建议通过后端代理请求。

基础 URL

所有 API 的基础 URL 为：

https://api.jisuapi.com/agent

核心接口

接口 方法 说明 计费
search POST 搜索可用工具 按 Token
execute POST 执行指定工具 按工具计费
stats GET 查询执行统计 免费
stats_detail GET 详细统计记录 免费
stats_dashboard GET 数据面板 免费

快速示例

1. 搜索工具

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

2. 执行工具

curl -X POST "https://api.jisuapi.com/agent/execute" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "shouji_query",
    "params": {
      "mobile": "13800138000"
    }
  }'

响应格式

成功响应

{
  "status": 0,
  "msg": "ok",
  "result": {
    // 接口返回数据
  },
  "request_id": "req_..."
}

错误响应

{
  "status": 101,
  "msg": "APPKEY为空或不存在",
  "result": null
}

常见错误

认证错误

HTTP 状态码status说明
401101APPKEY 为空或不存在
401102APPKEY 已过期
403103APPKEY 无请求此数据权限

业务错误

status说明
301工具 ID 不存在
302工具参数缺失或格式错误
303搜索查询为空
304未找到匹配的工具

完整错误码列表请查看 错误码参考。

请求限制

频率限制

超限响应

{
  "status": 106,
  "msg": "IP请求超过限制",
  "result": null
}

提示：如需提高限制，请联系客服。

最佳实践

1. 使用连接池

复用 HTTP 连接，提高性能：

import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(total=3, backoff_factor=0.3)
adapter = HTTPAdapter(max_retries=retry)
session.mount('https://', adapter)

2. 处理超时

设置合理的超时时间：

response = requests.post(
    url,
    json=data,
    headers=headers,
    timeout=30  # 30秒超时
)

3. 错误处理

完善的错误处理逻辑：

try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    result = response.json()
    
    if result['status'] == 0:
        # 处理成功
        pass
    else:
        # 处理业务错误
        print(f"错误: {result['msg']}")
except requests.exceptions.Timeout:
    print("请求超时")
except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

4. 保存 request_id

用于追踪和排查问题：

request_id = result.get('request_id')
logger.info(f"请求ID: {request_id}")

详细 API 文档

查看各接口的完整文档：

SDK 和工具

即将推出

目前请使用 HTTP 客户端库直接调用，参考 使用示例。

下一步

需要帮助？如有其他问题，请联系客服微信或发送邮件至 kf@jisuapi.com