HHOLOVE AI 开放平台/开发者/技术文档

懂鸟动物识别 API

v2.0.0

懂鸟 API 是一个异步 API 集合，供用户调用提供识别结果以及动物百科文字资料的 API。API 系统中的动物特指以下类别，超出此范围目前不能支持。请注意当前版本号及类别支持的版本号。

Base URL
https://ai.open.hhodata.com/api/v2
Content-Type
multipart/form-data
Authentication
api_key
数据许可
CC BY 4.0
下载 OpenAPI 规范

支持的动物类别

类别标识识别支持版本号识别支持类别数量百科支持版本号百科支持类别数量
鸟B1.0111512.011271
兽M2.038202.16649
两栖A2.055892.28689
爬行R2.085922.212019
其他1F3.0敬请期待3.1敬请期待
其他2S3.1敬请期待3.2敬请期待
POST

上传图片

/dongniao

上传图片必须上传一个 2M 以内的原始图片。附带裁剪格式为可选，如没有则服务会尝试进行主体识别，如带有指定位置则使用该位置裁剪后进行识别。为保证最佳识别效果，指定位置应该为正方形并保证动物主体居中并最大化。

Header Parameters
api_keystringrequired
调用的 api_key
Request Body Schema multipart/form-data
imagestring <binary>required
上传图片
uploadstringrequired
上传数量，目前必须为 1，只支持 1 张图片识别
classstringoptional
缺省为 'B'，即只返回鸟类。必须为 'ABMR' 之组合。如 'BM' 表示返加鸟类与兽类识别结果
x1integeroptional
指定识别位置的左上角 x 坐标
y1integeroptional
指定识别位置的左上角 y 坐标
x2integeroptional
指定识别位置的右下角 x 坐标
y2integeroptional
指定识别位置的右下角 y 坐标
areastring <binary>optional
见附录 1，使用国家、地区编码过滤识别结果。鸟类支持部分国家/地区的二级地区，其他只支持到国家/地区
didstringrequired
设备/客户端唯一 ID。1-32 位，只能大小写字母或数字，可以为客户设备 ID 的 md5 hash 值，用于调试及必要情况下进行统计
Responses
200返回值含义描述
返回值含义描述
1000正常返回返回信息为识别 ID，请使用获取结果 API 获取相关 ID 的识别结果；
1001图片大小错误图片大小错误，超过 2M或太小；
1002图片格式错误错误的图片格式。仅支持 jpg，且最小边长必须大于 50，最大边长小于8192；
1003设备 ID 错误设备 ID 为 1-32 位只能为大小写字母及数字；
1004动物种类错误动物种类必须为 BMARFS 的组合或空白。2.0 只支持 BMAR 或空白（缺省只返回鸟类识别结果）；
1005地区错误地区必须在支持范围内；
1006IP 调用 IP 地址锁定如用户设定调用 IP 地址锁定；
1011物种不在地区范围内检测到动物，但该物种不在当前地区分布范围内；
Response Schema application/json
status
string
自定义状态码
message
string
状态码描述
data
object
└─recognitionId
string
返回信息为识别 ID，请使用获取结果 API 获取相关 ID 的识别结果
400错误请求
Response Schema application/json
status
string
自定义状态码
message
string
状态码描述
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \
  -H "api_key: YOUR_API_KEY" \
  -F "image=@bird.jpg" \
  -F "upload=1" \
  -F "class=BM" \
  -F "did=DEVICE_ID"
POST

上传鸟鸣（语音识别）

/dongniao

上传一段鸟鸣音频识别鸟种。与图片识别共用 upload / resultid 通道及同一套 api_key、配额与限流，仅上传时传 sound 文件（而非 image）。上传成功后返回任务 ID，再用「获取识别结果」接口轮询；服务端按任务 ID 自动区分图像与语音，语音结果结构见下。

  • 音频支持 mp3 / wav / m4a / flac / ogg，最大 5MB
  • 语音按上传音频时长累加秒数计费（向上取整、识别成功才计），与图像配额相互独立
  • 结果查询复用「获取识别结果」接口，传同一 resultid 即可；处理中同样返回 1001，间隔 1~3 秒轮询重试
Header Parameters
api_keystringrequired
调用的 api_key
Request Body Schema multipart/form-data
soundstring <binary>required
音频文件（mp3 / wav / m4a / flac / ogg，最大 5MB）
uploadstringrequired
上传数量，固定填 1
areastringoptional
见附录 1，使用国家、地区编码进行地理分布过滤；缺省按 WORLD 不过滤
didstringoptional
设备/客户端唯一 ID。1-32 位，只能大小写字母或数字
Responses
200返回值含义描述
返回值含义描述
1000正常返回返回任务 ID（格式与图片识别一致），请使用「获取识别结果」接口轮询查询语音识别结果；
1001音频大小错误音频文件超过 5MB；
1002音频格式错误缺少 sound 文件或音频格式无效；
1003设备 ID 错误设备 ID 为 1-32 位只能为大小写字母及数字；
1005地区错误地区编码无效或不在支持范围内；
语音识别结果结构：用「获取识别结果」接口轮询语音任务时，返回为一个字典：duration 为音频时长（秒）；summary 为全局物种汇总，按置信度降序，每项为 [物种ID, 置信度(0~1), 学名, 中文名]；splits 为分时间段结果，每项为 [起始秒, 结束秒, [该段物种列表]]，段内物种项结构同 summary。物种 ID 可继续用「获取百科资料」接口取详情。
400错误请求
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \
  -H "api_key: YOUR_API_KEY" \
  -F "sound=@bird.mp3" \
  -F "upload=1"
POST

获取识别结果

/dongniao

在使用上传图片 API 得到识别 ID 后，在稍后时候（至少 1 秒后）调用该接口获取识别结果。如果识别已完成，系统将返回结果。

Header Parameters
api_keystringrequired
调用的 api_key
Request Body Schema multipart/form-data
resultidstring <binary>required
识别ID
Responses
200返回值含义描述
返回值含义描述
1000识别结果识别结果在返回信息中，此时返回信息为一个数组，具体描述见后；
1001结果未生成结果未生成，必要情况下 1 秒后重试。请限定重试次数，如超过 5 次仍未得到识别结果，可认为识别已超时。
1008没有检测到动物目标图片中未检测到动物目标；
1009没有识别出动物虽然可以检测到动物，但未能识别出动物；
识别结果说述：识别结果为一组数组，表明该图片可识别出多少个单独的动物目标及其类别。每一个数据组为一个包括“box”及“list”元素的字典。“box”为 4 个元素的数组，分别表示长方形左上角与右下角两点之座标。“list” 为不超过 10 条按照识别准确率倒序之数组，每一个数组元素包含另一四个元素之数组，分别为“置信度”、“中文名|英文名|拉丁名”、“ID”、“动物类别”。注意本列表可能为空，表明不能识别出相关动物。
Response Schema application/json
status
string
data
object
└─recognitionId
string
└─animal
string
└─confidence
number
400系统异常
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \
  -H "api_key: YOUR_API_KEY" \
  -F "resultid=HH-BM_20240713_05483816735_1-ABCDEFG"
POST

获取百科资料

/dongniao

根据获取结果中的 ID 与动物类别，可以获取该动物的百科资料。注意：百科资料描述由 AI 整理，请自行判断其准确性与适用场景。

Header Parameters
api_keystringrequired
调用的 api_key
Request Body Schema multipart/form-data
animalidinteger <binary>required
动物 ID
classstring <binary>required
动物类别，'ABMR' 之一
Responses
200返回值含义描述
返回值含义描述
1000百科内容识别结果在返回信息中，此时返回信息为一个百科信息字典，具体内容参考附例。
1004动物类别错误动物种类必须为 BMARFS 的组合或空白。2.0 只支持 BMAR 或空白（缺省只返回鸟类识别结果）；
1010动物 ID 错误不存在的动物 ID 或当前未支持该动物类别百科查询。
Response Schema application/json
status
string
data
object
└─recognitionId
string
└─animal
string
└─confidence
number
400系统异常
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \
  -H "api_key: YOUR_API_KEY" \
  -F "animalid=2245" \
  -F "class=B"
POST

查询配额剩余次数

/dongniao

查询当前 api_key 的已用次数、总额度和剩余次数。

  • 本接口不消耗配额，可放心调用
  • 配额耗尽（used >= total）时仍能返回，便于客户端确认“已用完”
  • 限流 60 次/分钟（按 api_key + IP 维度）
  • 仅支持 api_key 鉴权（web_token 不支持）
Header Parameters
api_keystringrequired
调用的 api_key
Request Body Schema multipart/form-data
quotastring <binary>required
固定填 1
Responses
200返回值含义描述
返回值含义描述
1000查询成功返回 used / total / remaining / status 四个字段。total=-1 表示无限额度，此时 remaining 也为 -1。
1005Key 不匹配api_key 不存在、已禁用或调用方使用了 web_token（不支持）。
1006IP 不在白名单Key 绑定了 IP 白名单而调用方 IP 不匹配。
1007触发限流每 api_key + IP 每分钟限 60 次。HTTP 503。
400系统异常
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \
  -H "api_key: YOUR_API_KEY" \
  -F "quota=1"
APPENDIX · 文档附录

配套资料与协议

附录 1 · 地区与地区码对照表
area 参数所需的国家 / 地区编码完整列表
→
附录 2 · AI 开放平台服务协议
PDF 文档，接入前请阅读并同意
→
数据许可 · CC BY 4.0
百科文字资料采用 CC BY 4.0，使用须署名（来源：懂鸟 / HHOLOVE）并保留许可链接
→
限时福利
联系客服，领取免费测试额度
商务合作 / 技术咨询 / 问题反馈 service@hholove.com
回复最快
企业微信官方账号
免费测试 · 接入指导 · 技术支持
企业微信二维码
钉钉企业可用
企业级方案、私有部署咨询
钉钉二维码
个人微信备用
企业微信无法使用时请使用此方式
个人微信二维码