博识生 API · 开发者技术文档

QUICK START

三步完成第一次识别

在控制台创建应用后，系统将提供 Client ID 与 Client Secret。请务必将凭据妥善存放在服务端环境变量中。

1. 保存凭据

Client Secret 仅生成展示一次，请切勿存入前端代码或公开代码库。

2. 换取 Token

通过客户端凭据协议，换取 24 小时有效的 Bearer 访问令牌。

3. 提交照片

携带 Token 调用多物种识别接口，实时解析植物、鸟类、昆虫等生命物种。

AUTHENTICATION

获取访问令牌 (Token)

使用 HTTP Basic 认证传递 Client ID 和 Client Secret，发送 grant_type=client_credentials。Token 默认有效期 86,400 秒（24小时）。

POST /api/open/v1/token

cURL 请求示例

curl -X POST "https://你的域名/api/open/v1/token" \
  -u "$BIOSNAP_CLIENT_ID:$BIOSNAP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials"

成功返回 (HTTP 200 OK)：

JSON 响应

{
  "access_token": "bst_f49b1a82c0e84b72...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "recognize"
}

安全警示： 不要从浏览器或小程序前端直接换取 Token。Client Secret 必须存放在您的独立业务服务端，由您的服务端中转调用博识生 API。

CODE SAMPLES

完整多语言调用示例

以下示例演示完整的“获取 Token → 上传照片 → 打印识别结果”工作流。

Shell · Bash

# 1. 换取 Token
TOKEN=$(curl -sS -X POST "https://你的域名/api/open/v1/token" \
  -u "$BIOSNAP_CLIENT_ID:$BIOSNAP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" | python3 -c \
  'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 2. 上传照片识别
curl -X POST "https://你的域名/api/open/v1/recognize" \
  -H "Authorization: Bearer $TOKEN" \
  -F "image=@observation.jpg" \
  -F "model=whole_knn"

Python 3.9+

import os
import requests

base_url = "https://你的域名"

# 1. 换取 Token
token_resp = requests.post(
    f"{base_url}/api/open/v1/token",
    auth=(os.environ["BIOSNAP_CLIENT_ID"], os.environ["BIOSNAP_CLIENT_SECRET"]),
    data={"grant_type": "client_credentials"},
    timeout=15,
)
token_resp.raise_for_status()
token = token_resp.json()["access_token"]

# 2. 调用物种识别
with open("observation.jpg", "rb") as f:
    resp = requests.post(
        f"{base_url}/api/open/v1/recognize",
        headers={"Authorization": f"Bearer {token}"},
        files={"image": ("observation.jpg", f, "image/jpeg")},
        data={"model": "whole_knn"},
        timeout=60,
    )
resp.raise_for_status()
print(resp.json())

Node.js 18+ (Fetch API)

import { readFile } from "node:fs/promises";

const baseUrl = "https://你的域名";
const credentials = Buffer.from(
  `${process.env.BIOSNAP_CLIENT_ID}:${process.env.BIOSNAP_CLIENT_SECRET}`
).toString("base64");

// 1. 换取 Token
const tokenRes = await fetch(`${baseUrl}/api/open/v1/token`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: "grant_type=client_credentials",
});
if (!tokenRes.ok) throw new Error(await tokenRes.text());
const { access_token } = await tokenRes.json();

// 2. 上传照片识别
const form = new FormData();
form.set("image", new Blob([await readFile("observation.jpg")], { type: "image/jpeg" }), "observation.jpg");
form.set("model", "whole_knn");

const res = await fetch(`${baseUrl}/api/open/v1/recognize`, {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}` },
  body: form,
});
if (!res.ok) throw new Error(await res.text());
console.log(await res.json());

RECOGNITION ENDPOINT

物种识别接口

POST /api/open/v1/recognize

请求格式为 multipart/form-data，请求头需携带 Authorization: Bearer bst_...。

参数字段	类型	必填	说明
`image`	File	必填	JPEG、PNG 或 WebP 格式图像文件，大小不超过 10 MiB。
`model`	String	可选	模型版本：`whole_knn`（默认深度新版）或 `legacy`（经典版）。
`box`	String	可选	指定局部框选坐标：`x1,y1,x2,y2`（原图像素坐标）。

标准响应示例 (HTTP 200 OK)：

JSON 结果

{
  "request_id": "req_01K89V...",
  "model": "whole_knn",
  "abstain": false,
  "size": [1920, 1280],
  "boxes": [
    { "box": [120.0, 80.0, 960.0, 720.0], "conf": 0.96 }
  ],
  "top": [
    {
      "latin": "Papilio xuthus",
      "cn": "柑橘凤蝶",
      "clade": "昆虫",
      "score": 0.912
    },
    {
      "latin": "Papilio machaon",
      "cn": "金凤蝶",
      "clade": "昆虫",
      "score": 0.054
    }
  ]
}

SYSTEM ENDPOINTS

模型列表与应用信息

GET /api/open/v1/models

获取当前服务支持的模型及物种收录数量。

JSON 响应

{
  "models": {
    "whole_knn": { "available": true, "n_classes": 82916 },
    "legacy": { "available": true, "n_classes": 82917 }
  }
}

GET /api/open/v1/me

查询当前应用凭证的限流配置与配额消耗。

JSON 响应

{
  "app_id": "app_01K78...",
  "name": "自然记录小程序",
  "limits": { "qps": 5, "rpm": 120, "rpd": 50000 },
  "usage": { "total_requests": 1420, "today_requests": 128 }
}

ERROR CODES

错误码全集

invalid_token 401 访问令牌无效、损坏或已过期，请重新请求 /token 换取。

rate_limit_exceeded 429 已超出 QPS 或每分钟/每日调用频度限制，请稍后重试。

insufficient_quota 429 总调用配额已用尽，请联系管理员扩充。

invalid_image 400 上传的文件不是有效的图像文件或已损坏。

app_disabled 403 当前应用已在控制台被管理员禁用。