快速开始
- 1
注册并实名认证
在开放平台注册账号，完成主体认证（内测阶段由商务开通）。
- 2
创建 API Key
在控制台创建 Key，默认获得免费额度（100 次/日）。
- 3
按文档调用
使用 curl 或 SDK 调用识别接口，5 分钟内拿到第一个结果。
鉴权方式
所有开放接口通过请求头 X-API-Key 鉴权。Key 与租户绑定，可在控制台创建、禁用与轮换。
鉴权
# 所有开放接口通过请求头携带 API Key
X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxx
# 建议
# 1) Key 只在服务端使用，禁止写入前端代码或公开仓库
# 2) 按环境拆分 Key（测试 / 生产），便于独立配额与吊销
# 3) 定期轮换：新 Key 生效后观察 24h 再停用旧 Key接口参考
下表为 v1 能力目录；每个核心接口附请求与响应示例。
POST/v1/ai/pest-recognize病虫害识别
上传作物叶片/田块照片，返回病虫害类别、置信度与处置处方。同步接口，超时建议 10s；批量场景请使用异步模式。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | file | 是 | 图片文件，支持 jpg/jpeg/png/webp，单张 ≤10MB |
crop | string | 否 | 作物类型（如 strawberry / tomato），提供可提升准确率 |
async | bool | 否 | true 走异步队列，返回 task_id 供轮询 |
请求示例
curl -X POST https://ai.aiotagro.com/api/v1/ai/pest-recognize \
-H "X-API-Key: $AIOTAGRO_API_KEY" \
-F "image=@leaf.jpg" \
-F "crop=strawberry"响应示例
{
"code": 0,
"data": {
"label": "白粉病",
"confidence": 0.93,
"prescription": "摘除病叶；加强通风降湿；按当地植保指南轮换用药",
"suggestion_id": "sug_20261016_0001",
"model_version": "pest-v1.4"
}
}POST/v1/ai/growth-recognize长势与杂草识别
基于田块影像评估出苗率、株高与长势等级，可返回变量作业处方图地址。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | file | 是 | 田块影像（建议正射或俯拍） |
plot_id | string | 否 | 地块标识，用于长势趋势比对 |
响应示例
{
"code": 0,
"data": {
"plot_id": "P-1024",
"emergence_rate": 0.91,
"growth_grade": "良好",
"prescription_map_url": "https://.../prescription.png?sign=...",
"captured_at": "2026-10-16T09:12:00Z"
}
}POST/v1/ai/agri-qa农技问答（RAG）
检索增强问答，回答附引用来源，适合嵌入控制台、小程序与客服系统。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
question | string | 是 | 用户问题，建议 ≤200 字 |
crop | string | 否 | 限定作物范围，提升召回质量 |
请求示例
curl -X POST https://ai.aiotagro.com/api/v1/ai/agri-qa \
-H "X-API-Key: $AIOTAGRO_API_KEY" -H "Content-Type: application/json" \
-d '{"question":"大棚草莓花期湿度多少合适？","crop":"strawberry"}'响应示例
{
"code": 0,
"data": {
"answer": "草莓花期空气相对湿度建议控制在 40%–60%……",
"references": [
{ "source": "设施草莓生产技术规程", "section": "4.2 花期管理" }
]
}
}GET/v1/devices设备列表
查询租户下设备与在线状态（设备接入后可用）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
farm_id | string | 否 | 按基地筛选 |
online | bool | 否 | 仅返回在线/离线设备 |
cursor | string | 否 | 分页游标，默认每页 50 |
响应示例
{
"code": 0,
"data": {
"items": [
{ "device_id": "SN-8801", "name": "3号棚温湿度", "brand": "generic", "online": true,
"last_seen": "2026-10-16T09:20:31Z", "battery": 87 }
],
"next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}
}GET/v1/telemetry遥测数据
按设备与时间范围查询遥测序列。必须携带时间范围，否则返回 400（对齐分区裁剪要求）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_id | string | 是 | 设备标识 |
metrics | string | 否 | 指标列表，逗号分隔（temp,humidity…） |
from / to | ISO8601 | 是 | 时间范围（UTC），单次跨度建议 ≤7 天 |
interval | string | 否 | 聚合粒度 raw|1h|1d，默认 raw |
响应示例
{
"code": 0,
"data": {
"device_id": "SN-8801",
"interval": "1h",
"points": [
{ "ts": "2026-10-16T08:00:00Z", "temp": 23.4, "humidity": 62.1, "soil_moist": 31.5 }
]
}
}错误码
| 业务码 | HTTP | 说明 |
|---|---|---|
0 | 200 | 成功 |
INVALID_PARAM | 400 | 参数缺失或格式错误 |
UNAUTHORIZED | 401 | API Key 缺失或失效 |
QUOTA_EXCEEDED | 429 | 超出配额（含免费额度） |
IMAGE_TOO_LARGE | 413 | 图片超过 10MB 上限 |
MODEL_BUSY | 503 | 推理队列繁忙，请重试或改用异步接口 |
限流与配额
| 项 | 取值 | 备注 |
|---|---|---|
| 免费额度 | 100 次/日 / Key | 用于联调与评估，超出返回 429 |
| 默认限流 | 5 次/秒 / Key（突发 10） | 按 Key 维度，网关层拦截 |
| 单图大小 | ≤10MB | 超出返回 413 IMAGE_TOO_LARGE |
| 同步超时 | 10s（建议） | 超时建议改异步，避免重复计费 |
| 调用日志 | 保留 ≥90 天 | 控制台可查用量/成功率/时延 |
SDK 与示例
当前提供 curl 与 Node.js 示例；Python/Java SDK 规划中。
curl
curl -X POST https://ai.aiotagro.com/api/v1/ai/pest-recognize \
-H "X-API-Key: $AIOTAGRO_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "image=@leaf.jpg" \
-F "crop=strawberry"
# 200 OK
{
"code": 0,
"data": {
"label": "白粉病",
"confidence": 0.93,
"prescription": "摘除病叶；加强通风降湿；按当地植保指南轮换用药",
"suggestion_id": "sug_20261016_0001"
}
}Node.js
import { readFile } from 'node:fs/promises'
const res = await fetch('https://ai.aiotagro.com/api/v1/ai/pest-recognize', {
method: 'POST',
headers: { 'X-API-Key': process.env.AIOTAGRO_API_KEY! },
body: (() => {
const fd = new FormData()
fd.append('crop', 'strawberry')
return fd
})(),
})
const { data } = await res.json()
console.log(data.label, data.confidence, data.prescription)最佳实践
失败重试要带退避
遇到 429 / 503 建议指数退避重试（1s→2s→4s，最多 3 次），不要原地密集重试。
大批量走异步
单次 >50 张时使用 async=true，用 task_id 轮询结果，避免同步超时与连接占用。
图片质量优先于尺寸
建议长边 1000–1600px、主体清晰、避免强逆光；过小的图片会显著降低识别准确率。
时间一律 UTC
遥测与告警接口的时间字段统一 UTC（ISO8601），展示层按本地时区转换。
先对账再扩容
通过调用统计核对配额与账单；异常增长先排查 Key 泄露。
本页为 v1 设计稿（内测阶段）。接口路径、字段、配额与计费口径以开放平台正式文档为准；识别结果为辅助决策信息，涉及用药与植保处置请遵循当地农业主管部门指南。