寻亲网 API 文档

为开发者提供的寻亲网 API 接口说明

目录

API 概述

寻亲网 API 允许开发者以编程方式访问寻亲网的数据和功能。通过这些 API，您可以：

  • 获取寻亲信息列表
  • 获取寻亲信息详情
  • 搜索寻亲信息
  • 获取寻亲类型列表
  • 获取统计数据

所有 API 请求都应该发送到基础 URL：https://xunqin.icu/api/v1

所有响应都以 JSON 格式返回。

认证方式

寻亲网 API 使用 API 密钥进行认证。您需要在开发者中心申请 API 密钥，并在每个请求中包含它。

有两种方式可以包含您的 API 密钥：

  1. 查询参数：将 api_key 作为查询参数添加到 URL 中。

    https://xunqin.icu/api/v1/people?api_key=YOUR_API_KEY

  2. 请求头：将 X-API-Key 作为请求头添加。

    X-API-Key: YOUR_API_KEY

错误码说明

当 API 请求失败时，您将收到一个包含错误信息的 JSON 响应和相应的 HTTP 状态码。

状态码 错误码 描述
400 BAD_REQUEST 请求参数错误
401 UNAUTHORIZED 未提供 API 密钥或 API 密钥无效
403 FORBIDDEN 没有权限访问请求的资源
404 NOT_FOUND 请求的资源不存在
429 TOO_MANY_REQUESTS 超出 API 请求限制
500 INTERNAL_SERVER_ERROR 服务器内部错误

错误响应示例：

{ "code": "UNAUTHORIZED", "message": "无效的 API 密钥", "status": 401 }

API 端点

GET /people

获取寻亲信息列表

返回寻亲信息列表，支持分页。

查询参数

参数名 类型 必填 描述
page 整数 否 页码，默认为 1
limit 整数 否 每页记录数，默认为 20，最大为 100
type 整数 否 寻亲类型 ID
province 字符串 否 省份名称
status 整数 否 状态：0-寻找中，1-已找到

响应

{ "code": 0, "msg": "success", "data": { "total": 120, "per_page": 20, "current_page": 1, "last_page": 6, "data": [ { "id": 1, "name": "张三", "gender": 1, "gender_text": "男", "age": 35, "avatar_images": "avatar1.jpg,avatar2.jpg", "avatar_images_array": [ "avatar1.jpg", "avatar2.jpg" ], "characteristic": "身高175cm，左手臂有一个月牙形胎记", "native_place": "河南省郑州市", "missing_time": "2010-05-12", "missing_place": "北京市海淀区", "missing_days": 4745, "contact_name": "李四", "contact_phone": "13800138000", "status": 0, "status_text": "寻找中", "type_id": 1, "seekType": { "id": 1, "name": "寻亲生" }, "missingLocale": { "province": "北京市", "city": "海淀区" }, "created_at": "2023-01-01 12:00:00", "updated_at": "2023-01-01 12:00:00" } ] } }
GET /people/{id}

获取寻亲信息详情

返回指定 ID 的寻亲信息详情。

路径参数

参数名 类型 必填 描述
id 整数 是 寻亲信息 ID

响应

{ "code": 0, "msg": "success", "data": { "id": 1, "name": "张三", "gender": 1, "gender_text": "男", "age": 35, "avatar_images": "avatar1.jpg,avatar2.jpg", "avatar_images_array": [ "avatar1.jpg", "avatar2.jpg" ], "characteristic": "身高175cm，左手臂有一个月牙形胎记", "native_place": "河南省郑州市", "missing_time": "2010-05-12", "missing_place": "北京市海淀区", "missing_days": 4745, "contact_name": "李四", "contact_phone": "13800138000", "status": 0, "status_text": "寻找中", "type_id": 1, "seekType": { "id": 1, "name": "寻亲生" }, "missingLocale": { "province": "北京市", "city": "海淀区" }, "created_at": "2023-01-01 12:00:00", "updated_at": "2023-01-01 12:00:00", "detail": "张三于2010年5月12日在北京市海淀区走失，当时穿着蓝色T恤和黑色裤子。如有线索，请联系李四，电话13800138000。" } }
GET /types

获取寻亲类型列表

返回所有寻亲类型。

响应

{ "code": 0, "msg": "success", "data": [ { "id": 1, "name": "寻亲生", "description": "寻找失散多年的亲生子女", "missing_people_count": 45 }, { "id": 2, "name": "寻亲人", "description": "寻找失散多年的亲人", "missing_people_count": 32 }, { "id": 3, "name": "认亲", "description": "寻找自己的亲生父母", "missing_people_count": 28 }, { "id": 4, "name": "寻友", "description": "寻找失联的朋友", "missing_people_count": 15 } ] }
GET /stats

获取统计数据

返回寻亲网的统计数据。

响应

{ "code": 0, "msg": "success", "data": { "total_count": 120, "found_count": 35, "active_count": 85, "success_rate": 29.17, "type_stats": [ { "id": 1, "name": "寻亲生", "missing_people_count": 45 }, { "id": 2, "name": "寻亲人", "missing_people_count": 32 }, { "id": 3, "name": "认亲", "missing_people_count": 28 }, { "id": 4, "name": "寻友", "missing_people_count": 15 } ], "province_stats": [ { "province": "河南省", "count": 25 }, { "province": "广东省", "count": 18 }, { "province": "四川省", "count": 15 }, { "province": "湖北省", "count": 12 }, { "province": "山东省", "count": 10 } ] } }

MCP API 调用

寻亲网提供了基于 Model Context Protocol (MCP) 的 API 接口，允许开发者以编程方式访问寻亲网的数据和功能。MCP 是一种用于大型语言模型 (LLM) 与外部系统交互的协议，通过 MCP API，您可以：

  • 获取寻亲网的资源和工具列表
  • 读取特定的寻亲信息资源
  • 调用寻亲网提供的工具执行操作
  • 使用人脸识别技术进行寻亲匹配

所有 MCP API 请求都应该发送到基础 URL：https://xunqin.icu/api/mcp

完整文档： 查看 MCP API 完整文档 获取更详细的信息，包括所有可用的资源、工具和示例代码。

主要 MCP 功能

功能 描述 端点
服务器信息 获取 MCP 服务器的基本信息和能力 GET /api/mcp/server-info
资源列表 获取可用的静态资源列表 GET /api/mcp/resources
资源模板列表 获取动态资源模板列表 GET /api/mcp/resource-templates
读取资源 根据 URI 读取特定资源的内容 GET /api/mcp/resource?uri=...
工具列表 获取可用的工具列表 GET /api/mcp/tools
调用工具 调用特定工具执行操作 POST /api/mcp/call-tool

人脸识别功能

POST /mcp/face-recognition

人脸识别匹配

通过上传人脸图片，使用 MCP (Missing Children Platform) 人脸识别技术进行寻亲匹配。

请求参数

请求体应为 multipart/form-data 格式，包含以下字段：

参数名 类型 必填 描述
image 文件 是 要进行识别的人脸图片，支持 JPG、PNG 格式，大小不超过 5MB
age 整数 否 图片中人物的大致年龄，用于提高匹配精度
gender 整数 否 性别：1-男，2-女，用于提高匹配精度
limit 整数 否 返回的最大匹配结果数量，默认为 10，最大为 50
threshold 浮点数 否 匹配阈值，范围 0-1，默认为 0.7，低于此值的匹配结果将被过滤

响应

{ "code": 0, "msg": "success", "data": { "matches": [ { "person_id": 42, "name": "王小明", "similarity": 0.89, "gender": 1, "gender_text": "男", "age": 12, "missing_time": "2018-06-15", "missing_place": "浙江省杭州市", "avatar_images_array": [ "person42_1.jpg", "person42_2.jpg" ], "status": 0, "status_text": "寻找中", "type_id": 1, "type_name": "寻亲生" }, { "person_id": 57, "name": "李明", "similarity": 0.78, "gender": 1, "gender_text": "男", "age": 13, "missing_time": "2019-03-22", "missing_place": "江苏省南京市", "avatar_images_array": [ "person57_1.jpg" ], "status": 0, "status_text": "寻找中", "type_id": 3, "type_name": "认亲" } ], "processing_time": "1.24s", "faces_detected": 1 } }

错误响应

{ "code": 1, "msg": "No face detected in the uploaded image", "data": null }

注意事项

  • 上传的图片必须包含清晰的人脸，否则将返回错误
  • 图片中如果包含多个人脸，系统将自动选择最大或最清晰的人脸进行识别
  • 为获得最佳匹配效果，建议上传正面、光线充足、表情自然的人脸照片
  • 此 API 调用会消耗更多的 API 配额，请合理使用
GET /mcp/face-recognition/status

获取人脸识别服务状态

获取 MCP 人脸识别服务的当前状态和使用统计信息。

响应

{ "code": 0, "msg": "success", "data": { "status": "online", "version": "3.2.1", "daily_usage": 45, "daily_limit": 1000, "total_usage": 1256, "accuracy_rate": 0.92, "average_processing_time": "1.35s" } }