正在打开使用指南…
◎Cosmo Core使用指南
官网进入工作台

开放平台

Java 后端接入示例

同步识别、X-API-Key、multipart、响应字段与错误处理。

适用:已拿到开放平台业务密钥,准备在后端服务里调用同步识别
示例代码:examples/java/CosmoSyncExample.java
接口契约:业务接入

1. 先确认三件事

  1. 应用已创建并处于启用状态;
  2. 已发放一把测试密钥(cosmo_ 开头,只展示一次);
  3. 应用允许调用模型(不选=全部),来源 IP 已按需加入白名单。

2. 认证怎么传

所有业务接口都使用请求头:

X-API-Key: cosmo_xxxxxxxxxxxxxxxxx

注意:

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}

4. Java 示例

示例使用:

依赖:

<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,包含:

4.1 这不是参数签名

X-API-Key 是静态 Bearer 凭证,不是用 model、conf、图片内容做 HMAC 算出来的。

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}
}

建议:

6. 状态码与重试

状态含义客户端动作
401密钥缺失/无效/过期不重试,检查密钥和到期时间
403应用停用、账号到期、模型/来源 IP 不允许不重试,按返回文案处理
413图片过大压缩后重试
422参数错误(模型、conf 等)修正参数,不重试
429并发/槽位/配额限制按 Retry-After 退避重试
500服务端异常有限重试;带上 incident_id 联系平台

生产建议:

7. 联调清单

需要异步任务、回调签名或 Java Spring Boot 版本时,继续看 业务接入 的异步任务章节。

8. 本次实测记录(2026-11-13)

已用本地服务完成端到端验证,不是只看代码:

限制:以上是本地环境验证;生产域名、HTTPS、实际网络和账号配额仍需按上线自检清单再跑一遍。