支持的动物类别
| 类别 | 标识 | 识别支持版本号 | 识别支持类别数量 | 百科支持版本号 | 百科支持类别数量 |
|---|---|---|---|---|---|
| 鸟 | B | 1.0 | 11151 | 2.0 | 11271 |
| 兽 | M | 2.0 | 3820 | 2.1 | 6649 |
| 两栖 | A | 2.0 | 5589 | 2.2 | 8689 |
| 爬行 | R | 2.0 | 8592 | 2.2 | 12019 |
| 其他1 | F | 3.0 | 敬请期待 | 3.1 | 敬请期待 |
| 其他2 | S | 3.1 | 敬请期待 | 3.2 | 敬请期待 |
POST
上传图片
/dongniao
上传不超过 2MB、可被服务端图像解析器读取的图片。图片的每条边必须为 11~8192 像素（含）；服务会自动进行主体检测。
Header Parameters
api_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
image
上传图片
upload
非空值，用于选择文件上传通道；建议固定填 1
class
缺省为 'B'。仅可由 B/M/A/R/F 组合；如 'BM' 表示返回鸟类与兽类识别结果
area
见附录 1，使用国家、地区编码过滤识别结果。鸟类支持部分国家/地区的二级地区，其他只支持到国家/地区
did
设备/客户端唯一 ID；提供时仅能为大小写字母或数字
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 正常返回 | 返回信息为识别 ID，请使用获取结果 API 获取相关 ID 的识别结果； |
| 1001 | 图片大小错误 | 图片超过 2MB； |
| 1002 | 图片格式或尺寸错误 | 图片无法解析，或任一边不在 11~8192 像素范围内； |
| 1003 | 设备 ID 错误 | did 已提供但包含非字母数字字符； |
| 1004 | 动物种类错误 | class 包含 B/M/A/R/F 以外的字符； |
| 1005 | 地区错误 | 地区编码非法或不在支持范围内； |
Response Schema application/json
[0]
integer
业务状态码，1000 表示任务已受理
[1]
string
识别 ID（resultid），用于轮询获取识别结果
400错误请求
Response Schema application/json
[0]
integer
业务状态码
[1]
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
URL 提交图片识别
/dongniao
通过图片 URL 提交识别任务，服务端异步下载图片后进行识别。与「上传图片」使用相同的结果查询通道，但传 url 而不是 image 文件，且无需传 upload 参数。
- URL 需可被服务端访问；服务端最多跟随 2 次重定向，下载超时为 5 秒
- 服务端下载失败或无法解析为图片时，不会在提交阶段报错；请轮询「获取识别结果」，失败时返回 1001（URL download failed）
- 结果查询传同一 resultid；处理中同样返回 1001，建议间隔 1~3 秒轮询并限定重试次数
Header Parameters
api_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
url
图片 URL（服务端异步下载）
class
缺省为 'B'；仅可由 B/M/A/R/F 组合。非法值会回退为 'B'
area
见附录 1，使用国家、地区编码过滤识别结果
did
设备/客户端唯一 ID。1-32 位，只能大小写字母或数字
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 正常返回 | 返回识别 ID，请使用获取识别结果 API 轮询相关 ID； |
| 1003 | 设备 ID 错误 | 设备 ID 为 1-32 位只能为大小写字母及数字； |
| 1005 | 地区错误 | 地区编码无效或不在支持范围内； |
异步下载失败：提交成功仅表示任务已受理。URL 下载失败或图片无法解析时，在轮询结果阶段返回
[1001, "URL download failed"]。400错误请求
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \ -H "api_key: YOUR_API_KEY" \ --data-urlencode "url=https://example.com/animal.jpg" \ -d "class=ABMR"
POST
上传鸟鸣（语音识别）
/dongniao
上传一段鸟鸣音频识别鸟种。与图片识别共用 upload / resultid 通道及同一套 api_key、配额与限流，仅上传时传 sound 文件（而非 image）。上传成功后返回任务 ID，再用「获取识别结果」接口轮询；服务端按任务 ID 自动区分图像与语音，语音结果结构见下。
- 音频支持 mp3 / wav / m4a / flac / ogg，最大 5MB
- 语音按上传音频时长累加秒数计费（向上取整、识别成功才计），与图像配额相互独立
- 结果查询复用「获取识别结果」接口，传同一 resultid 即可；处理中同样返回 1001，间隔 1~3 秒轮询重试
Header Parameters
api_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
sound
音频文件（mp3 / wav / m4a / flac / ogg，最大 5MB）
upload
上传数量，固定填 1
area
见附录 1，使用国家、地区编码进行地理分布过滤；缺省按 WORLD 不过滤
did
设备/客户端唯一 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
URL 提交鸟鸣（语音识别）
/dongniao
通过音频 URL 提交鸟鸣识别，服务端下载音频后识别。与「上传鸟鸣」等价，只是用 sound_url 传 URL 而非上传 sound 文件（单独提交时无需 upload 参数）。返回任务 ID，再用「获取识别结果」接口轮询，结果结构与语音上传一致。
- 音频下载上限 5MB，支持 mp3 / wav / m4a / flac / ogg，URL 无扩展名时按 mp3 解码
- 按语音时长累加秒数计费（向上取整、识别成功才计），与图像配额相互独立
- 结果查询复用「获取识别结果」接口，传同一 resultid 即可；处理中同样返回 1001，间隔 1~3 秒轮询重试
Header Parameters
api_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
sound_url
音频文件 URL（服务端下载，上限 5MB，支持 mp3 / wav / m4a / flac / ogg）
area
见附录 1，使用国家、地区编码进行地理分布过滤；缺省按 WORLD 不过滤
did
设备/客户端唯一 ID。1-32 位，只能大小写字母或数字
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 正常返回 | 返回任务 ID（格式与图片识别一致），请使用「获取识别结果」接口轮询查询语音识别结果； |
| 1002 | 音频 URL 错误 | 缺少 sound_url；或服务端下载失败 / 非音频（下载与解码在轮询结果阶段执行，失败时轮询返回 1002）； |
| 1003 | 设备 ID 错误 | 设备 ID 为 1-32 位只能为大小写字母及数字； |
| 1005 | 地区错误 | 地区编码无效或不在支持范围内； |
语音识别结果结构：与「上传鸟鸣」完全一致 ——
duration 时长（秒）、summary 全局物种汇总、splits 分段结果，详见上一节。若 URL 下载失败或非音频，轮询结果返回 [1002, "Sound url error"]。400错误请求
POST/dongniao
curl -X POST https://ai.open.hhodata.com/api/v2/dongniao \ -H "api_key: YOUR_API_KEY" \ --data-urlencode "sound_url=https://example.com/bird.mp3"
POST
获取识别结果
/dongniao
提交图片、图片 URL、鸟鸣文件或鸟鸣 URL 后，使用同一 resultid 轮询本接口。处理中返回 [1001, resultid]；成功或终态失败均以 [code, payload] 返回。
Header Parameters
api_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
resultid
识别ID
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 识别结果 | 识别结果在返回信息中，此时返回信息为一个数组，具体描述见后； |
| 1001 | 结果未生成 | 结果未生成，必要情况下 1 秒后重试。请限定重试次数，如超过 5 次仍未得到识别结果，可认为识别已超时。 |
| 1008 | 未检测到目标框 | 图片中未检测到目标框（No boxes）； |
| 1009 | 地区编码错误 | 结果处理时检测到无效地区编码； |
| 1010 | 未识别到动物 | 图片中未识别出动物（No animals）； |
| 1011 | 物种不在地区范围内 | 识别到物种，但不在所传地区的分布范围内； |
识别结果说述：识别结果为一组数组，表明该图片可识别出多少个单独的动物目标及其类别。每一个数据组为一个包括“box”及“list”元素的字典。“box”为 4 个元素的数组，分别表示长方形左上角与右下角两点之座标。“list” 为不超过 10 条按照识别准确率倒序之数组，每一个数组元素包含另一四个元素之数组，分别为“置信度”、“中文名|英文名|拉丁名”、“ID”、“动物类别”。注意本列表可能为空，表明不能识别出相关动物。
Response Schema application/json
[0]
integer
业务状态码
[1]
array | string | object
成功时为图像检测数组或语音结果对象；处理中/失败时为说明字符串
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_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
animalid
动物 ID
class
动物类别；缺省为 B，可传 B/M/A/R/F
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 百科内容 | 识别结果在返回信息中，此时返回信息为一个百科信息字典，具体内容参考附例。 |
| 1004 | 动物类别错误 | 多字符 class 包含 B/M/A/R/F 以外的字符； |
| 1010 | 动物 ID 错误 | 不存在的动物 ID 或当前未支持该动物类别百科查询。 |
Response Schema application/json
[0]
integer
业务状态码
[1]
object | string
成功时为百科资料对象；失败时为说明字符串
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_key
调用的 api_key
Request Body Schema multipart/form-data 或 application/x-www-form-urlencoded
quota
固定填 1
Responses
200返回值含义描述
| 返回值 | 含义 | 描述 |
|---|---|---|
| 1000 | 查询成功 | 返回 image 与 song 两个配额对象，并保留顶层 used / total / remaining 作为图像配额兼容字段。total=-1 表示无限额度。 |
| 1005 | Key 不匹配 | api_key 不存在、已禁用或调用方使用了 web_token（不支持）。 |
| 1006 | IP 不在白名单 | 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"
