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

开放平台

开放平台使用指南

申请、登录、应用、密钥、用量、追踪、任务和成员。

面向:客户、业务方、开发者、账号 owner、平台运营
入口:/open · 控制台:/open/console
返回总册:产品使用说明书

一、开放平台是什么

开放平台是 Cosmo Core 对外的开发者门户。它把“申请账号 → 创建应用 → 领密钥 → 调接口 → 看用量 → 排障”做成自助流程。

开放平台不等于内部控制台:

二、公开页面

1. 首页 /open

提供产品能力介绍、接入流程、起步代码和入口:

2. 接入文档 /open/docs

按场景组织接口说明:

3. API 参考 /open/reference

从公开的 OpenAPI 契约自动渲染接口和字段,适合查参数、看响应结构、下载 OpenAPI。

4. 申请接入 /open/apply

未知客户从这里开始。需要填写:

提交成功后会得到:

查询进度:在申请页下方输入申请号 + 提交时的联系人。状态包括:

查询不需要登录。错误联系人不返回申请是否存在,查询接口有限流。

三、登录与账号

登录

打开 /open/login(独立登录页,交付给客户的链接用这个),或直接打开 /open/console——未登录时同样显示登录卡片;使用平台分配的业务账号登录。登录页支持 ?next= 回跳(只接受站内 /open 路径),例如从「控制台」入口进来,登录后直接落到原目标页(含 ?tab= 分区):

首次开通或 owner 重置后拿到的临时密码只展示一次。开放平台当前没有自助改密入口:成员密码可由账号 owner 重置,本人密码需要平台运营协助重置。

第一个人员超级管理员怎么来

系统不会自动创建人员超管。初始化顺序是:

  1. 在服务器 /etc/cosmo-core.env 配置 ADMIN_API_KEYS(环境管理密钥);
  2. 打开 /login,选「API Key 登录」,输入这把环境密钥;
  3. 进入「管理中心 → 人员权限 → 创建人员账号」,角色选「管理员」,创建第一个人员超管;
  4. 保存创建响应里只展示一次的临时密码;
  5. 退出环境密钥登录,改用刚创建的用户名 + 临时密码登录;
  6. 首次登录后修改密码,再绑定手机号;
  7. 后续的「系统集成」配置页,只能由这个 users.role=admin 的人员超管操作。

ADMIN_API_KEYS 是 break-glass 环境密钥,没有人员身份、手机号和审计姓名;它可以创建第一个人员超管,但不能进「系统集成」配置页。人员超管也可以在「人员权限」里继续创建其他 admin/review/predict 账号。

账号与成员

一个业务账号可以有多个成员:

账号角色能做什么
owner创建应用、发放/轮换/撤销密钥、编辑应用配置、添加/移除成员、调整 owner、重置成员密码
member只读查看应用、用量、任务、成员;不能创建应用或管理密钥

登录后可以在控制台顶部的账号下拉框切换账号。管理员登录时可能同时看到内部平台和业务账号。

账号状态

概览底部会显示账号健康预警:

出现预警时先看提示,再联系平台运营处理。账号到期/停用后调用会被拒绝。

四、控制台布局

登录后 /open/console 分为五个分区:

分区内容
概览账号状态、额度、24h 调用/失败、接入进度、健康预警
应用与密钥应用列表、应用配置、密钥发放/轮换/撤销、接入代码
调用与追踪用量、每日趋势、request_id 追踪
任务异步任务列表、任务详情、取消、回调重试
成员账号成员、owner/member、重置密码

分区使用 ?tab= 保留刷新状态,例如:

/open/console?tab=apps
/open/console?tab=calls

五、概览

账号摘要

接入进度

四步:

  1. 账号已开通
  2. 创建第一个应用
  3. 发放测试密钥
  4. 完成第一次调用

已完成的步骤打勾,当前步骤高亮;右侧按钮会直接带到下一步。

健康预警

有异常才显示:

没有异常时不会出现空白提示条。

六、应用与密钥

应用是什么

应用是一次接入的边界。一个账号可以有多个应用,例如:

应用属性:

字段说明谁能改
应用名称业务可识别的名称owner 可改
APP ID公开标识,不带权限不可改
环境测试 / 生产创建时选择
状态启用 / 停用owner 可改
复核回调地址人工复核结果回调业务方owner 可改
可用模型不选=全部;由平台运营配置平台运营
能力识别 / 反馈平台运营
每秒/每日配额跟随全局、不限或具体值平台运营
来源 IP 白名单限制可调用来源平台运营
密钥数当前有效密钥数量发放/撤销时变化

创建应用

在「应用与密钥」或概览下一步点击「创建应用」:

创建后自动订阅 AI 视觉产品,并生成回调签名密钥。

应用配置

打开应用「管理」后,owner 可以修改:

保存后立即生效。普通成员只读。

可用模型、能力、配额、IP 白名单由平台运营在内部控制台配置;如需调整联系平台运营。

密钥

密钥是调用接口的凭据:

回调签名密钥

用于业务方验证平台回调:

接入代码

应用详情提供 cURL 示例:

curl -X POST https://<域名>/v1/vision/predict_upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "model=sort" \
  -F "conf=0.3" \
  -F "file=@sample.jpg"

把 YOUR_API_KEY 替换为刚发放的密钥。需要 URL 识别、异步任务或反馈时查看 /open/docs。

六·补、第一次接入最短路径

业务调研或第一次联调,按下面顺序走,不要先写业务代码:

  1. 在开放平台创建应用,发一把测试密钥;
  2. 用密钥调 GET /v1/vision/models,确认 200 并看到 default_model、models[];
  3. 用 POST /v1/vision/predict_upload 上传一张真实图片,确认返回 request_id;
  4. 把 request_id 写入业务表,再连续跑 20 张真实业务图人工核对;
  5. 调一次 /v1/vision/feedback,确认返回 entered_review_pool;
  6. 联调通过后再发生产密钥,撤销测试密钥。

认证头只使用:

X-API-Key: cosmo_xxx

不要使用 Authorization: Bearer,不要把密钥放进 URL、前端、日志或 Git。API Key 身份调用不需要 X-Requested-With,也不要自行设置 X-Cosmo-Ingress。

第一条请求:

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"

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"

失败时按状态码处理:401 检查密钥,403 检查应用/账号/模型/IP,413 压缩图片,422 检查 model 和 conf,429 按 Retry-After 退避。

六·补二、Java 后端示例

需要把同步识别接到 Java 后端时,按 Java 同步接入示例 操作:

Java 17 + Jackson 的核心调用:

MultipartBodyBuilder body = new MultipartBodyBuilder();
body.part("file", new FileSystemResource(image));
body.part("model", "sort");
body.part("conf", 0.3);

PredictResponse result = restClient.post()
    .uri("/v1/vision/predict_upload")
    .contentType(MediaType.MULTIPART_FORM_DATA)
    .body(body.build())
    .retrieve()
    .body(PredictResponse.class);

六·补三、App ID、密钥与参数签名

业务接入时先把四个对象分开:

对象例子是否秘密作用
业务账号acct_...否客户归属:成员、额度、到期时间
应用app_...否一次接入边界:模型、能力、配额、IP、回调地址
API Keycosmo_...是调用接口的凭证,放在 X-API-Key
回调签名密钥whsec_...是只用于校验平台回调,不用于调用业务接口

层级是:

业务账号
  └─ 应用(app_id 公开)
       ├─ API Key(cosmo_...,秘密)
       └─ 回调签名密钥(whsec_...,秘密)

当前认证不是参数签名

调用方式:

POST /v1/vision/predict_upload
X-API-Key: cosmo_xxx
Content-Type: multipart/form-data

平台的处理顺序:

  1. 对 X-API-Key 做哈希查询,确认密钥存在、未撤销、未过期;
  2. 检查应用启用、业务账号启用且未到期;
  3. 检查网络入口、来源 IP;
  4. 检查识别能力、可用模型、配额;
  5. 处理图片、推理、落库,返回 request_id。

参数 model、conf、图片本身不需要做 HMAC/加密运算。它们通过 HTTPS 传输,服务端按字段规则校验。当前接口没有“请求参数签名”机制;密钥是静态 Bearer 凭证,不是从参数计算出来的。只有平台回调业务方时,才用 whsec_ 回调密钥对 timestamp + "." + body 做 HMAC-SHA256 验签。

因此不要:

泄露处理:立即在控制台撤销该密钥,发新密钥,检查调用记录;不要只改应用名称。

六·补四、账号安全(2026-11-14)

登录后控制台新增「账号安全」分区:

开关默认关闭。生产回填以下环境变量并重启:

PHONE_BINDING_ENABLED=1
SMS_ENABLED=1
PHONE_ENC_KEY=...
PHONE_HASH_PEPPER=...
SMS_PROVIDER=tencent
SMS_TENCENT_SECRET_ID=...
SMS_TENCENT_SECRET_KEY=...
SMS_TENCENT_SDK_APP_ID=...
SMS_TENCENT_SIGN_NAME=...
SMS_TEMPLATE_BIND=...
SMS_TEMPLATE_NOTIFY=...
SMS_TENCENT_REGION=ap-guangzhou

腾讯云短信签名/模板未审核时保持 SMS_ENABLED=0,页面不能完成绑定;本地开发且 ALLOW_ANONYMOUS=1 时可返回调试验证码。

六·补五、系统集成(超级管理员)

/console-next/admin?tab=integrations 提供「系统集成」页,只允许平台管理员人员账号操作:

角色边界:

配置后如何验收

  1. 人员超管进入「系统集成」,保存腾讯云短信和微信网站应用配置;
  2. 点「运行自检」:检查密钥/模板/回调地址/管理员手机号是否齐全;
  3. 在账号安全绑定管理员手机号,点「发送测试短信」;
  4. 打开 /open/login,点「微信扫码登录」,确认授权、绑定和登录;
  5. 未绑定微信扫码时,应提示先用账号密码登录后绑定,不应自动创建账号;
  6. 失败时进入「运行监控 → 错误与系统事件」,来源筛选「集成」,点「查看」→「复制排查包」,把排查包和截图发给研发。

排查包只包含时间、接口、故障编号、摘要、堆栈摘要和版本,不含 SecretKey、AppSecret、完整手机号或请求体。

腾讯云短信需先在控制台完成签名、模板报备;微信需先完成网站应用审核和回调域配置。

微信网站应用回调地址填写:

https://ai.banmahuanao.com/open/wechat/callback

微信后台的「授权回调域」填写 ai.banmahuanao.com。登录页在微信配置开启后显示「微信扫码登录」;未绑定账号扫码会提示先用账号密码登录后在「账号安全」绑定,不会自动创建业务账号。

七、调用与追踪

用量

支持:

展示:

可导出 CSV。

request_id 追踪

在「调用与追踪」输入识别返回的 request_id,可以看:

外部账号只能查看自己业务账号下应用产生的调用;查不到时先确认 request_id 是否属于当前账号。

八、异步任务

任务用于长耗时或需要回调的调用:

重点字段:

字段含义
task_id任务 ID
statusqueued / running / succeeded / failed / canceled
callback_statusnone / pending / sent / failed
attempts已执行次数
callback_attempts回调尝试次数
result成功后的识别结果
error失败原因

九、成员管理

owner 可以:

规则:

十、错误与排障

状态常见原因处理
401密钥无效、过期、撤销;未登录检查 X-API-Key;重新登录
403应用停用、账号到期/停用、能力或 IP 不允许看返回文案;联系平台运营
404request_id/任务不存在或不属于当前账号确认 ID 和账号
409任务已结束、回调不可重试、申请已处理看任务/申请状态
413图片或上传超过限制压缩/换图
422参数格式错误(模型、conf、字段)看字段说明
429配额、并发或槽位繁忙稍后重试或联系运营调整配额
500服务内部错误记录 incident_id,查看调用追踪

排障顺序:

  1. 看响应状态和 detail
  2. 保存 request_id / incident_id
  3. 到「调用与追踪」查 request_id
  4. 确认账号/应用/密钥/配额/IP
  5. 仍无法解决时提供 request_id、时间、应用 ID 和错误文案给平台运营

十一、安全与边界

十二、常见问题

申请提交后多久能通过?
由平台运营审批,没有自动时限;用申请号 + 联系人查询状态。

审批通过后没有收到密码?
首个登录账号的临时密码只展示一次,由审批人/运营交付;审批通过后的弹窗支持一键复制(登录地址 /open/login + 账号 + 临时密码 + 改密提示),直接发给申请人即可;丢失后请联系运营或 owner 重置。

怎么修改自己的登录密码?
开放平台当前没有自助改密入口;请联系账号 owner 重置成员密码,或联系平台运营协助。人员账号在内部控制台右上角账号菜单可以自行修改密码。

为什么创建应用后没有可用模型?
可用模型由平台运营配置;默认不选表示全部,若被限制则只能使用授权模型。

为什么调用返回 429?
可能是每秒/每日配额、并发上限或推理槽位繁忙;看响应文案,必要时调整配额或重试。

为什么回调没有到?
看任务详情 callbacks:可能是无回调地址、签名失败、业务方返回非 2xx 或重试用尽。owner 可重试回调。

为什么外部追踪查不到?
只能查当前业务账号下应用产生的调用;跨账号不可见。

能修改可用模型/IP 白名单吗?
开放平台 owner 只能改应用名称、状态、回调地址;模型、能力、配额、IP 由平台运营配置。


需要接口字段和错误码细节时,继续看 业务接入。
需要内部运营/复核/模型发布操作时,看 控制台卷。