开放平台
Java 后端接入示例
同步识别、X-API-Key、multipart、响应字段与错误处理。
适用:已拿到开放平台业务密钥,准备在后端服务里调用同步识别
示例代码:examples/java/CosmoSyncExample.java
接口契约:业务接入
1. 先确认三件事
- 应用已创建并处于启用状态;
- 已发放一把测试密钥(
cosmo_开头,只展示一次); - 应用允许调用模型(不选=全部),来源 IP 已按需加入白名单。
2. 认证怎么传
所有业务接口都使用请求头:
X-API-Key: cosmo_xxxxxxxxxxxxxxxxx
注意:
- 只放在后端请求头,不放进浏览器、URL 查询参数或前端 localStorage;
- 不要设置
X-Cosmo-Ingress,它由 Nginx 按入口设置; - API Key 身份调用不需要
X-Requested-With(该头只用于浏览器会话防 CSRF); - 密钥只展示一次,丢失后由 owner 轮换或联系平台运营。
3. 同步识别接口
上传文件(推荐)
POST /v1/vision/predict_upload
X-API-Key: cosmo_xxx
Content-Type: multipart/form-data
file=@scene.jpg
model=sort
conf=0.3
图片 URL
POST /v1/vision/predict
X-API-Key: cosmo_xxx
Content-Type: application/json
{"image":"https://images.example.com/scene.jpg","model":"sort","conf":0.3}
model:sort(垃圾分类)、luodi(垃圾落地);不传使用默认模型;conf:0.05–1,建议先 0.25–0.4;- 文件最大 10 MiB,像素上限 2500 万;
conf只影响返回给你的框,低于阈值的候选仍会入库供复核。
4. Java 示例
示例使用:
- Java 17+
- JDK
HttpClient - Jackson(
jackson-databind)
依赖:
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.17.2</version>
</dependency>
环境变量:
export COSMO_BASE_URL="https://ai.banmahuanao.com" # 内网环境可换成内网域名
export COSMO_API_KEY="cosmo_xxx" # 不要提交到代码仓库
运行:
java com.banma.cosmo.CosmoSyncExample /path/to/scene.jpg sort 0.3
客户端核心调用:
CosmoVisionClient client = new CosmoVisionClient(baseUrl, apiKey);
PredictResponse result = client.predictUpload(imagePath, "sort", 0.3);
String requestId = result.requestId(); // 必须写入业务表
int count = result.count();
String annotated = result.annotatedImage();
完整代码见 CosmoSyncExample.java,包含:
- multipart 构造;
X-API-Key请求头;- 同步响应 DTO;
- 429 的
Retry-After读取; annotated_image带 Key 拉取示例;- 不打印密钥。
4.1 这不是参数签名
X-API-Key 是静态 Bearer 凭证,不是用 model、conf、图片内容做 HMAC 算出来的。
- 直接把完整
cosmo_...放进请求头; - 参数通过 HTTPS 传输,由服务端校验;
- 不要在客户端加密参数或把密钥拼进 URL;
- 不要用
whsec_回调密钥调用业务接口;回调密钥只用于验证平台回调。
5. 返回字段怎么用
{
"request_id": "0b7f...",
"model": "sort",
"model_version": "v2-glass",
"model_sha256": "...",
"count": 2,
"detections": [
{"class": "金属", "class_id": 4, "confidence": 0.78, "bbox": [556.6, 253.05, 625.89, 370.59]}
],
"annotated_image": "/annotated/xxx.jpg",
"image_width": 1280,
"image_height": 720,
"performance": {"inference_ms": 51.2, "server_total_ms": 68.4}
}
建议:
- 按
class_id做业务判断,class中文名仅展示; - 把
request_id写入业务表,后续反馈、复核和排障都靠它; count=0不代表平台没记录,低阈值候选仍可被复核;source/annotated_image是相对路径,访问时同样带X-API-Key;- 失败时记录 HTTP 状态、
detail和平台返回的incident_id(如有),不要只记录“失败”。
6. 状态码与重试
| 状态 | 含义 | 客户端动作 |
|---|---|---|
| 401 | 密钥缺失/无效/过期 | 不重试,检查密钥和到期时间 |
| 403 | 应用停用、账号到期、模型/来源 IP 不允许 | 不重试,按返回文案处理 |
| 413 | 图片过大 | 压缩后重试 |
| 422 | 参数错误(模型、conf 等) | 修正参数,不重试 |
| 429 | 并发/槽位/配额限制 | 按 Retry-After 退避重试 |
| 500 | 服务端异常 | 有限重试;带上 incident_id 联系平台 |
生产建议:
- 429 不要立即重试,按
Retry-After秒数等待; - 同步接口设置 30–60 秒超时;
- 业务侧保存请求 ID,避免重复上传同一张图片产生多条记录;
- 密钥放环境变量/密钥管理服务,禁止写入日志、Git 或前端。
7. 联调清单
- [ ] 测试密钥能调通
/v1/vision/predict_upload - [ ] 响应里有
request_id - [ ] 20 张真实业务图人工核对框位置
- [ ]
request_id已落业务表 - [ ] 429 能按
Retry-After退避 - [ ]
annotated_image能带 Key 拉取 - [ ] 错误响应记录状态码和
detail
需要异步任务、回调签名或 Java Spring Boot 版本时,继续看 业务接入 的异步任务章节。
8. 本次实测记录(2026-11-13)
已用本地服务完成端到端验证,不是只看代码:
- Java 示例
javac编译通过; - 本地创建 application + 测试密钥,密钥通过环境变量传入;
GET /v1/vision/models返回 200;POST /v1/vision/predict_upload使用sort、conf=0.05返回真实request_id和 67 个 detections,Java DTO 正确解析class_id、class、confidence、bbox;- 另一个样本返回 1 个 detection,用来确认单个结果也能解析;
- 错误密钥调用返回 401,错误信息为「调用凭据无效、已到期或已撤销」;
annotated_image带同一个X-API-Key拉取返回 200,内容为 JPEG。
限制:以上是本地环境验证;生产域名、HTTPS、实际网络和账号配额仍需按上线自检清单再跑一遍。