目标检测
返回类别、置信度和边界框,结果绑定实际权重版本与哈希,可追溯。
BANMAHUANAO OPEN PLATFORM
统一的应用、密钥、配额与用量管理。使用一个 API 完成图片识别、结果反馈和人工复核数据回流。
当前产品AI视觉其他业务产品接入中
curl -X POST https://ai.banmahuanao.com/v1/vision/predict_upload \ -H "X-API-Key: cosmo_xxx" \ -F "file=@scene.jpg" \ -F "model=luodi" \ -F "conf=0.4"
能力
返回类别、置信度和边界框,结果绑定实际权重版本与哈希,可追溯。
按业务场景选择模型;模型和版本由平台路由,业务方只声明要做什么。
业务反馈进入复核队列,人工标注沉淀为数据集,再进入模型评估与发布。
接入流程
提交产品线或企业信息,平台运营开通业务账号。
账号下创建应用,领取测试密钥,配置回调与能力范围。
按文档调用接口;在控制台查看调用量、成功率和配额。
准备好接入了吗?
已有账号请直接登录;还没有账号可以先提交接入申请。
API 文档
服务端调用,按业务账号授权。所有请求使用 X-API-Key;同步接口直接返回识别结果,异步接口返回任务并支持回调。
适合业务调研和第一次联调:先确认密钥可用,再上传一张真实图片,拿到可保存的 request_id。完整字段见后面「认证」和「上传图片识别」。
X-API-Key 只放在后端请求头,不要放进浏览器或 URL。开放平台 → 控制台 → 应用 → 发放密钥。把 cosmo_... 完整值放进环境变量;如果应用配置了模型或来源 IP 白名单,确认当前后端在允许范围内。
export COSMO_BASE_URL="https://ai.banmahuanao.com" export COSMO_API_KEY="cosmo_xxx" curl "$COSMO_BASE_URL/v1/vision/models" \ -H "X-API-Key: $COSMO_API_KEY"
返回 default_model 和 models[];后续 model 参数使用 models[].name,例如 sort 或 luodi。如果这里就返回 401/403,先不要继续联调,按错误码检查密钥、应用状态和账号状态。
curl -X POST "$COSMO_BASE_URL/v1/vision/predict_upload" \ -H "X-API-Key: $COSMO_API_KEY" \ -F "file=@scene.jpg" \ -F "model=sort" \ -F "conf=0.3"
成功时重点看四件事:request_id、model_version、count、detections。把 request_id 写入业务表;后续反馈、复核、排障都依赖它。
request_id;/v1/vision/feedback,确认返回 entered_review_pool;| 现象 | 优先检查 |
|---|---|
| 401 | 密钥是否完整、是否过期、是否把前缀当成完整密钥 |
| 403 | 应用是否启用、账号是否到期、模型/IP 是否在允许范围 |
| 413 | 图片是否超过 10 MB 或 2500 万像素 |
| 422 | model 是否在模型列表里、conf 是否在 0.05–1 |
| 429 | 按响应头 Retry-After 退避,不要立即重试 |
接口按产品划分命名空间,AI视觉的路径统一以 /v1/vision 开头。旧根路径保留兼容,但新接入请使用本文档中的路径。
| 场景 | 建议 | 接口 |
|---|---|---|
| 单张图片、需要立即拿到结果 | 同步 | /v1/vision/predict_upload 或 /predict |
| 大图、批量、峰谷明显、可接受排队 | 异步 | /v1/vision/tasks/upload,完成后回调或轮询 |
| 结果需要人工复核回流 | 同步或异步均可 | 拿到 request_id 后调用 /feedback |
所有业务接口都必须带应用密钥。密钥在开放平台创建应用后发放,只在创建密钥时展示一次,服务端保存哈希。
| 请求头 | 必填 | 说明 |
|---|---|---|
X-API-Key | 是 | 形如 cosmo_xxx;不要放在 URL、前端代码或日志中 |
Content-Type | 按接口 | JSON 接口为 application/json;上传接口使用 multipart/form-data |
Idempotency-Key | 否 | 仅异步创建任务使用;同一应用内相同值返回同一任务,建议用业务单号 |
curl https://ai.banmahuanao.com/v1/vision/models \ -H "X-API-Key: cosmo_xxx"
| 对象 | 例子 | 是否秘密 | 作用 |
|---|---|---|---|
| 业务账号 | acct_... | 否 | 客户归属,承载成员、额度和到期时间 |
| 应用 | app_... | 否 | 一次接入的边界,决定可用模型、能力、配额、IP 白名单和回调地址 |
| API Key | cosmo_... | 是 | 应用下的调用凭据;请求时放在 X-API-Key |
| 回调签名密钥 | whsec_... | 是 | 只用于业务方校验平台回调,不用于调用业务接口 |
一个账号可以有多个应用,一个应用可以有多把密钥;密钥属于应用,不能跨应用使用。业务接口不需要再传 App ID:服务端用 API Key 反查出所属应用和权限。
X-API-Key;whsec_ 回调密钥做 HMAC-SHA256 验签。密钥只在发放时展示一次,服务端保存哈希;泄露后立即撤销并重新发放。测试和生产使用不同应用/密钥,密钥只放后端环境变量或密钥管理服务。
| 项目 | 限制 | 说明 |
|---|---|---|
| 图片格式 | JPEG / PNG / WEBP | 服务端统一转 JPEG |
| 单图大小 | 10 MB | 超限返回 413 |
| 单图像素 | 2500 万像素 | 防止解压炸弹 |
置信度 conf | 0.05 – 1 | 低于该值的检测框不返回;默认 0.4 |
| 图片 URL | 平台授权域名 | 需将对象存储/CDN 域名加入平台白名单,建议预签名 URL |
| 来源 IP | 按应用配置 | 应用可配置来源 IP/CIDR 白名单;留空不限制 |
| 账号配额 | 按账号 | QPS、日额度、总额度、并发上限,超限返回 429 |
图片 URL 只允许 http/https;内网/保留地址会被拒绝。没有白名单需求时,优先使用上传接口。
/v1/vision/models返回当前应用可用模型、默认模型、类别和权重哈希。模型是否存在、版本和类别由平台路由决定,业务方不需要维护权重版本。
无请求体。认证头见「认证」。
| 字段 | 类型 | 说明 |
|---|---|---|
default_model | string | 当前应用未指定 model 时使用的模型名 |
product | object | 产品信息:id、name |
models[] | array | 可用模型列表;应用未授权的模型不会返回 |
models[].name | string | 调用时传给 model 的名称,例如 luodi |
models[].version | string | 当前激活权重版本 |
models[].description | string | 模型用途说明 |
models[].classes | object | {class_id: 类别名},用于解释检测结果 |
models[].sha256 | string | 激活权重哈希,便于追溯 |
models[].pending_migration | boolean | true 时类别定义与权重不一致,暂不可推理 |
{
"default_model": "luodi",
"product": {"id": "vision", "name": "AI视觉"},
"models": [{
"name": "luodi",
"version": "best",
"description": "落地垃圾检测",
"classes": {"0": "落地垃圾", "1": "其他"},
"sha256": "c85c447d...",
"pending_migration": false
}]
}
/v1/vision/predict传图片 URL 做同步推理。URL 必须使用平台授权域名;如果图片在客户内网或临时文件,请使用上传接口。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | string | 是 | 图片 URL,最长 4096;需要加入平台图片域名白名单 |
model | string | 否 | 模型名;不传时使用应用默认模型 |
conf | number | 否 | 置信度阈值 0.05–1,默认 0.4 |
curl -X POST https://ai.banmahuanao.com/v1/vision/predict \
-H "X-API-Key: cosmo_xxx" \
-H "Content-Type: application/json" \
-d '{"image":"https://cdn.example.com/scene.jpg","model":"luodi","conf":0.4}'
| 字段 | 类型 | 说明 |
|---|---|---|
request_id | string | 本次识别 ID,用于反馈、复核、排障和幂等 |
model | string | 实际使用的模型 |
model_version | string | 实际权重版本 |
model_sha256 | string | 实际权重哈希 |
source | string | 服务端保存的原图相对路径;拉取时需带 API Key |
count | number | 达到 conf 的检测框数量 |
detections[] | array | 检测结果列表 |
detections[].class_id | number | 类别 ID,对应模型 classes |
detections[].class | string | 类别名称 |
detections[].confidence | number | 置信度 0–1 |
detections[].bbox | number[4] | 像素坐标 [x1,y1,x2,y2],原点在左上角 |
annotated_image | string | 画框后的图片相对路径 |
image_width / image_height | number | 原图像素尺寸 |
performance | object | 各阶段耗时(毫秒)和图片字节数,见「结果字段」 |
{
"request_id": "ea844e1ecd974ae39489f8ea09730927",
"model": "luodi",
"model_version": "best",
"model_sha256": "c85c447d...",
"source": "/uploads/6f971f28.jpg",
"count": 2,
"detections": [
{"class_id": 0, "class": "落地垃圾", "confidence": 0.9321, "bbox": [120.5, 88.0, 420.2, 360.7]},
{"class_id": 1, "class": "其他", "confidence": 0.612, "bbox": [500.0, 210.4, 760.8, 402.1]}
],
"annotated_image": "/annotated/6f971f28.jpg",
"image_width": 1920,
"image_height": 1080,
"performance": {"fetch_ms": 188.2, "normalize_ms": 22.1, "ingest_ms": 210.3, "inference_ms": 430.7, "draw_ms": 12.4, "persist_ms": 8.1, "server_total_ms": 661.5, "image_bytes": 1823400}
}
/v1/vision/predict_upload直接上传图片做同步推理,适合内网系统、相机抓拍和临时文件。请求使用 multipart/form-data。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | JPEG/PNG/WEBP,最大 10 MB,2500 万像素 |
model | string | 否 | 模型名;不传使用应用默认模型 |
conf | number | 否 | 0.05–1,默认 0.4 |
curl -X POST https://ai.banmahuanao.com/v1/vision/predict_upload \ -H "X-API-Key: cosmo_xxx" \ -F "file=@scene.jpg" -F "model=luodi" -F "conf=0.4"
响应字段与「图片 URL 识别」完全一致。
下面是 Spring Boot 3 / Java 17 的最小调用片段;完整可运行的 JDK 版本见平台内使用指南 Java 后端接入示例,包含 multipart、错误解析和结果图访问。
Authorization: Bearer,不要把密钥写进前端、URL、日志或 Git。生产环境从环境变量/密钥管理服务读取。<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
@Service
public class CosmoVisionClient {
private final RestClient http;
public CosmoVisionClient(@Value("${cosmo.base-url}") String baseUrl,
@Value("${cosmo.api-key}") String apiKey) {
this.http = RestClient.builder()
.baseUrl(baseUrl)
.defaultHeader("X-API-Key", apiKey)
.build();
}
public PredictResponse predict(Path image, String model, double conf) {
MultipartBodyBuilder body = new MultipartBodyBuilder();
body.part("file", new FileSystemResource(image));
body.part("model", model);
body.part("conf", conf);
return http.post()
.uri("/v1/vision/predict_upload")
.contentType(MediaType.MULTIPART_FORM_DATA)
.body(body.build())
.retrieve()
.body(PredictResponse.class);
}
}
响应 DTO 至少保留 request_id、detections、annotated_image。业务判断用 class_id,不要依赖中文类别名;annotated_image 和 source 拉取时同样要带 X-API-Key。
如果使用 Java 8/11 或不用 Spring,看使用指南里的 JDK HttpClient 版本;不要为了示例引入不必要的框架。完整说明见 Java 后端接入示例。
/v1/vision/feedback把业务侧的真实结果回传给平台,用于复核回流和模型迭代。反馈是独立事件,不会覆盖已经完成的人工复核。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
request_id | string | 二选一 | 识别接口返回的 request_id,最推荐 |
image | string | 二选一 | 完整图片来源;与该应用的历史请求完全一致时才可反查 |
verdict | string | 是 | wrong 或 correct |
expected_class | string | 否 | 业务期望类别;wrong 时建议填写 |
note | string | 否 | 业务备注,最长 2000 |
curl -X POST https://ai.banmahuanao.com/v1/vision/feedback \
-H "X-API-Key: cosmo_xxx" -H "Content-Type: application/json" \
-d '{"request_id":"ea844e1e...","verdict":"wrong","expected_class":"落地垃圾","note":"现场误检"}'
| 字段 | 类型 | 说明 |
|---|---|---|
ok | boolean | 是否受理 |
request_id | string | 实际关联的识别 ID |
verdict | string | 原样返回 wrong/correct |
entered_review_pool | boolean | 是否因此进入待复核池 |
duplicate | boolean | 同一反馈是否已提交过(幂等) |
review_status | string | 当前复核状态:pending、confirmed、corrected、discarded、none |
already_reviewed | boolean | 是否已经有人工复核结论 |
{
"ok": true,
"request_id": "ea844e1ecd974ae39489f8ea09730927",
"verdict": "wrong",
"entered_review_pool": true,
"duplicate": false,
"review_status": "pending",
"already_reviewed": false
}
/v1/vision/tasksPOST/v1/vision/tasks/upload创建异步任务。URL 版本使用 JSON;上传版本使用 multipart。创建成功返回 202,任务由后台 worker 推理,完成后回调或由客户端轮询。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | string | URL 版本必填 | 图片 URL,规则同同步识别 |
file | file | 上传版本必填 | 图片文件,规则同同步上传 |
model | string | 否 | 模型名;不传使用应用默认模型 |
conf | number | 否 | 0.05–1,默认 0.4 |
priority | number | 否 | 0–5,默认 0;越大越优先,仅影响排队顺序 |
Idempotency-Key 请求头可选;同一应用内相同值返回同一任务。
curl -X POST https://ai.banmahuanao.com/v1/vision/tasks/upload \ -H "X-API-Key: cosmo_xxx" \ -H "Idempotency-Key: order-20261107-001" \ -F "file=@scene.jpg" -F "model=luodi" -F "conf=0.4" -F "priority=1"
| 字段 | 类型 | 说明 |
|---|---|---|
task_id | string | 任务 ID |
status | string | 创建时为 queued;后续为 running/succeeded/failed/canceled |
priority | number | 入队优先级 |
created_at | string | ISO 8601 创建时间 |
expires_at | string | 结果过期时间(默认 7 天) |
callback_status | string | none/pending/sent/failed |
callback_url | string|null | 应用配置的回调地址 |
{
"task_id": "task_2954c7a206ee42ba8d28063f422989e4",
"status": "queued",
"priority": 1,
"created_at": "2026-11-07T11:50:45.600+00:00",
"expires_at": "2026-11-14T11:50:45.600+00:00",
"callback_status": "none",
"callback_url": null
}
/v1/vision/tasks/{task_id}GET/v1/vision/tasks查询单个任务或最近任务。任务详情包含结果和最近 10 次回调记录;任务按应用隔离。
| 查询参数 | 类型 | 说明 |
|---|---|---|
task_id | path | 任务 ID |
limit | number | 列表接口返回数量,1–100,默认 50 |
状态:queued 排队、running 推理中、succeeded 成功、failed 失败、canceled 已取消。
| 字段 | 类型 | 说明 |
|---|---|---|
task_id | string | 任务 ID |
status | string | 当前状态 |
priority | number | 优先级 0–5 |
error | string|null | 失败或取消原因 |
result | object|null | 成功时为同步识别结果,字段见下方 |
callback_status | string | none/pending/sent/failed |
callback_attempts | number | 已尝试回调次数 |
callbacks[] | array | 最近回调记录:attempt、status_code、ts、error、response |
created_at / finished_at | string | 创建和完成时间 |
列表接口返回 {"items":[...]},item 字段同上。
/v1/vision/tasks/{task_id}/cancel/v1/vision/tasks/{task_id}/callback/retry取消排队/运行中的任务,或手动重试失败的回调。取消运行中的任务是协作式的:当前推理不会被打断,完成后丢弃结果并标记 canceled。
| 接口 | 响应 |
|---|---|
| 取消 | 返回更新后的任务;已结束任务返回 409 |
| 重试回调 | {"ok": true};无回调地址或未结束返回 409 |
应用配置回调地址后,任务完成/失败/取消会 POST 一条事件。回调失败按 30s / 5m / 30m / 2h / 24h 重试;最终失败后可在任务详情看到记录并手动重试。
| 请求头 | 说明 |
|---|---|
X-Cosmo-Event | task.completed 或 task.canceled |
X-Cosmo-Task-ID | 任务 ID |
X-Cosmo-Timestamp | Unix 秒级时间戳 |
X-Cosmo-Signature | v1=HMAC-SHA256(secret, timestamp + "." + 原始 body) |
X-Cosmo-Signature-Previous | 轮换后 24 小时内同时提供旧密钥签名 |
| 字段 | 类型 | 说明 |
|---|---|---|
event | string | task.completed / task.canceled |
task_id | string | 任务 ID |
status | string | succeeded / failed / canceled |
result | object|null | 成功时为识别结果 |
error | string|null | 失败/取消原因 |
{
"event": "task.completed",
"task_id": "task_2954c7a206ee42ba8d28063f422989e4",
"status": "succeeded",
"result": {"request_id": "ea844e1e...", "count": 2, "detections": [...]}
}
客户必须按 task_id 幂等;验签后建议检查时间戳窗口,防止重放。
同步识别和异步任务的 result 使用同一结构。
| 字段 | 类型 | 说明 |
|---|---|---|
request_id | string | 识别记录 ID,用于反馈和复核 |
model / model_version | string | 实际模型和权重版本 |
model_sha256 | string | 权重哈希 |
source | string | 服务端原图路径 |
count | number | 检测框数量 |
detections[].class_id / class | number / string | 类别 ID 和名称 |
detections[].confidence | number | 置信度 0–1 |
detections[].bbox | number[4] | 像素坐标,左上角原点 |
annotated_image | string | 画框图路径,带 API Key 拉取 |
image_width / image_height | number | 原图尺寸 |
performance.* | number | fetch/normalize/ingest/inference/draw/persist/server_total 毫秒,image_bytes 字节 |
错误响应体通常为 {"detail":"可执行的中文说明"};服务端异常返回 500,并带 incident_id 供排障。
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | 图片格式/内容无效 | 检查文件格式和大小 |
| 401 | 密钥无效、过期、被撤销,或应用停用 | 更换有效密钥;确认应用状态 |
| 403 | 模型/能力未开通、账号到期/停用、网络入口不允许 | 联系平台运营检查授权和网络策略 |
| 404 | 图片、任务或反馈来源不存在 | 检查 URL、task_id、request_id |
| 409 | 状态冲突,如图片 URL 对应多条记录、任务已结束 | 改用 request_id;刷新任务状态 |
| 413 | 图片或请求体超过大小限制 | 压缩图片或使用 URL 输入 |
| 422 | 参数不合法或缺少必填项 | 按字段表修正请求 |
| 429 | QPS/日额度/总额度/并发超限,或推理槽位繁忙 | 退避重试;检查配额和排队 |
| 500 | 服务端异常 | 带 incident_id 联系平台 |
API 参考
下面的接口、参数和响应字段直接来自服务端 OpenAPI 契约,不再手写维护。接口变化后刷新即可看到最新结构。
正在加载 OpenAPI 契约…
BANMAHUANAO OPEN PLATFORM
一个 API,完成图片识别、结果反馈与人工复核回流。应用、密钥、配额和用量都在一个控制台里。
接入进度
输入 request_id 后查看状态、耗时、结果和复核进度。
绑定后接收安全通知与账号到期提醒,并用于账号找回。
绑定后可用微信扫码登录,免输密码。
默认只发交易与安全类通知;站内通知始终保留。
调用失败?用 request_id ·
把 YOUR_API_KEY 替换为刚发放的密钥,先跑通一次上传识别。
需要 URL 识别、异步任务或反馈接口?
账号所有者可以在这里创建应用、发放/轮换/撤销密钥;普通成员只能查看。
你已登录,账号与额度可在「控制台」查看;这里仍可为其他项目提交新的接入申请。
© 2026 班马科技 · AI 视觉平台 · 晋ICP备2021013927号-1