开放平台
开放平台使用指南
申请、登录、应用、密钥、用量、追踪、任务和成员。
面向:客户、业务方、开发者、账号 owner、平台运营
入口:/open· 控制台:/open/console
返回总册:产品使用说明书
一、开放平台是什么
开放平台是 Cosmo Core 对外的开发者门户。它把“申请账号 → 创建应用 → 领密钥 → 调接口 → 看用量 → 排障”做成自助流程。
开放平台不等于内部控制台:
- 开放平台面向客户/业务方;
- 内部控制台面向平台管理员和复核人员;
- 两端共享同一套业务账号、应用、密钥、识别和调用数据。
二、公开页面
1. 首页 /open
提供产品能力介绍、接入流程、起步代码和入口:
- 首页
- 文档
- API 参考
- 控制台
- 申请接入
2. 接入文档 /open/docs
按场景组织接口说明:
- 5 分钟接入:发密钥 → 查模型 → 上传一张图 → 保存
request_id - 认证方式:请求头
X-API-Key - Java 后端:见 Java 同步接入示例
- 同步识别:
POST /v1/vision/predict(图片 URL) - 上传识别:
POST /v1/vision/predict_upload(文件) - 模型列表:
GET /v1/vision/models - 业务反馈:
POST /v1/vision/feedback - 异步任务:创建、列表、详情、取消、回调重试
- 错误码、响应字段、回调签名
- 示例代码
3. API 参考 /open/reference
从公开的 OpenAPI 契约自动渲染接口和字段,适合查参数、看响应结构、下载 OpenAPI。
4. 申请接入 /open/apply
未知客户从这里开始。需要填写:
- 产品线 / 公司名称
- 联系人(姓名/电话/邮箱,至少 2 个字符)
- 场景与需求说明
提交成功后会得到:
- 申请号,例如
apply_3f0b2d6d81d9 - 提示保存申请号和联系人
查询进度:在申请页下方输入申请号 + 提交时的联系人。状态包括:
- 审核中
- 已通过
- 未通过(可看审批备注)
查询不需要登录。错误联系人不返回申请是否存在,查询接口有限流。
三、登录与账号
登录
打开 /open/login(独立登录页,交付给客户的链接用这个),或直接打开 /open/console——未登录时同样显示登录卡片;使用平台分配的业务账号登录。登录页支持 ?next= 回跳(只接受站内 /open 路径),例如从「控制台」入口进来,登录后直接落到原目标页(含 ?tab= 分区):
- 用户名
- 密码
首次开通或 owner 重置后拿到的临时密码只展示一次。开放平台当前没有自助改密入口:成员密码可由账号 owner 重置,本人密码需要平台运营协助重置。
第一个人员超级管理员怎么来
系统不会自动创建人员超管。初始化顺序是:
- 在服务器
/etc/cosmo-core.env配置ADMIN_API_KEYS(环境管理密钥); - 打开
/login,选「API Key 登录」,输入这把环境密钥; - 进入「管理中心 → 人员权限 → 创建人员账号」,角色选「管理员」,创建第一个人员超管;
- 保存创建响应里只展示一次的临时密码;
- 退出环境密钥登录,改用刚创建的用户名 + 临时密码登录;
- 首次登录后修改密码,再绑定手机号;
- 后续的「系统集成」配置页,只能由这个
users.role=admin的人员超管操作。
ADMIN_API_KEYS 是 break-glass 环境密钥,没有人员身份、手机号和审计姓名;它可以创建第一个人员超管,但不能进「系统集成」配置页。人员超管也可以在「人员权限」里继续创建其他 admin/review/predict 账号。
账号与成员
一个业务账号可以有多个成员:
| 账号角色 | 能做什么 |
|---|---|
| owner | 创建应用、发放/轮换/撤销密钥、编辑应用配置、添加/移除成员、调整 owner、重置成员密码 |
| member | 只读查看应用、用量、任务、成员;不能创建应用或管理密钥 |
登录后可以在控制台顶部的账号下拉框切换账号。管理员登录时可能同时看到内部平台和业务账号。
账号状态
概览底部会显示账号健康预警:
- 账号停用
- 账号到期
- 额度使用 ≥80%
- 30 天内到期
出现预警时先看提示,再联系平台运营处理。账号到期/停用后调用会被拒绝。
四、控制台布局
登录后 /open/console 分为五个分区:
| 分区 | 内容 |
|---|---|
| 概览 | 账号状态、额度、24h 调用/失败、接入进度、健康预警 |
| 应用与密钥 | 应用列表、应用配置、密钥发放/轮换/撤销、接入代码 |
| 调用与追踪 | 用量、每日趋势、request_id 追踪 |
| 任务 | 异步任务列表、任务详情、取消、回调重试 |
| 成员 | 账号成员、owner/member、重置密码 |
分区使用 ?tab= 保留刷新状态,例如:
/open/console?tab=apps
/open/console?tab=calls
五、概览
账号摘要
- 账号状态:正常 / 停用 / 已到期
- 到期时间
- 总额度
- 24h 调用
- 24h 失败
- 并发上限
接入进度
四步:
- 账号已开通
- 创建第一个应用
- 发放测试密钥
- 完成第一次调用
已完成的步骤打勾,当前步骤高亮;右侧按钮会直接带到下一步。
健康预警
有异常才显示:
- 账号停用/到期
- 额度即将用尽
- 账号即将到期
没有异常时不会出现空白提示条。
六、应用与密钥
应用是什么
应用是一次接入的边界。一个账号可以有多个应用,例如:
- 测试应用
- 生产应用
- 不同项目/不同环境的应用
应用属性:
| 字段 | 说明 | 谁能改 |
|---|---|---|
| 应用名称 | 业务可识别的名称 | owner 可改 |
| APP ID | 公开标识,不带权限 | 不可改 |
| 环境 | 测试 / 生产 | 创建时选择 |
| 状态 | 启用 / 停用 | owner 可改 |
| 复核回调地址 | 人工复核结果回调业务方 | owner 可改 |
| 可用模型 | 不选=全部;由平台运营配置 | 平台运营 |
| 能力 | 识别 / 反馈 | 平台运营 |
| 每秒/每日配额 | 跟随全局、不限或具体值 | 平台运营 |
| 来源 IP 白名单 | 限制可调用来源 | 平台运营 |
| 密钥数 | 当前有效密钥数量 | 发放/撤销时变化 |
创建应用
在「应用与密钥」或概览下一步点击「创建应用」:
- 应用名称
- 环境:测试 / 生产
- 复核回调地址(可选)
创建后自动订阅 AI 视觉产品,并生成回调签名密钥。
应用配置
打开应用「管理」后,owner 可以修改:
- 应用名称
- 状态
- 复核回调地址
保存后立即生效。普通成员只读。
可用模型、能力、配额、IP 白名单由平台运营在内部控制台配置;如需调整联系平台运营。
密钥
密钥是调用接口的凭据:
- 发放:选择标签和有效天数
- 明文只在发放时展示一次;关闭后无法再查看
- 前缀用于识别,不能当密钥使用
- 到期前 14 天显示「即将到期(N 天)」
- 可在到期前轮换或撤销
- 撤销立即失效
回调签名密钥
用于业务方验证平台回调:
- owner 可见
- 轮换后旧密钥在 24 小时内仍随回调发送,之后失效
- 不要把回调密钥写进前端代码
接入代码
应用详情提供 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。
六·补、第一次接入最短路径
业务调研或第一次联调,按下面顺序走,不要先写业务代码:
- 在开放平台创建应用,发一把测试密钥;
- 用密钥调
GET /v1/vision/models,确认 200 并看到default_model、models[]; - 用
POST /v1/vision/predict_upload上传一张真实图片,确认返回request_id; - 把
request_id写入业务表,再连续跑 20 张真实业务图人工核对; - 调一次
/v1/vision/feedback,确认返回entered_review_pool; - 联调通过后再发生产密钥,撤销测试密钥。
认证头只使用:
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 同步接入示例 操作:
- 请求头
X-API-Key; - multipart 上传
file、model、conf; - 示例源码 CosmoSyncExample.java;
- 示例包含
request_id、detections、annotated_image和Retry-After; - 密钥只放环境变量,不要写进前端或仓库。
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 Key | cosmo_... | 是 | 调用接口的凭证,放在 X-API-Key |
| 回调签名密钥 | whsec_... | 是 | 只用于校验平台回调,不用于调用业务接口 |
层级是:
业务账号
└─ 应用(app_id 公开)
├─ API Key(cosmo_...,秘密)
└─ 回调签名密钥(whsec_...,秘密)
- 业务接口不需要传 App ID;平台用 API Key 反查应用,再读取应用的模型、能力、配额和 IP 白名单;
- 一个应用可以有多把密钥;密钥不能跨应用使用;
- App ID 可以出现在控制台、日志和排障信息里,但它不是凭据,不能拿来调用;
- 只有完整
cosmo_...能调用;只显示前缀是给人识别,不是可用密钥。
当前认证不是参数签名
调用方式:
POST /v1/vision/predict_upload
X-API-Key: cosmo_xxx
Content-Type: multipart/form-data
平台的处理顺序:
- 对
X-API-Key做哈希查询,确认密钥存在、未撤销、未过期; - 检查应用启用、业务账号启用且未到期;
- 检查网络入口、来源 IP;
- 检查识别能力、可用模型、配额;
- 处理图片、推理、落库,返回
request_id。
参数 model、conf、图片本身不需要做 HMAC/加密运算。它们通过 HTTPS 传输,服务端按字段规则校验。当前接口没有“请求参数签名”机制;密钥是静态 Bearer 凭证,不是从参数计算出来的。只有平台回调业务方时,才用 whsec_ 回调密钥对 timestamp + "." + body 做 HMAC-SHA256 验签。
因此不要:
- 把 API Key 和参数拼成签名再发送;
- 把密钥放进 URL、前端、日志或 Git;
- 把 App ID 当密钥;
- 把回调密钥当业务 API Key。
泄露处理:立即在控制台撤销该密钥,发新密钥,检查调用记录;不要只改应用名称。
六·补四、账号安全(2026-11-14)
登录后控制台新增「账号安全」分区:
- 手机号:自愿绑定;短信验证码验证后显示
138****8000和「已验证」; - 换绑:输入新手机号 + 验证码;解绑需要当前密码;
- 通知偏好:短信总开关 + 审批、密钥到期、额度、账号到期、安全、回调失败等事件开关;
- 平台管理员可在管理端查看成员手机号掩码,并显式「查看完整手机号」,该动作写审计;账号 owner 只看掩码;
- 手机号加密存储(AES-GCM/Fernet),另存 HMAC 哈希;验证码只存哈希;不写日志明文。
开关默认关闭。生产回填以下环境变量并重启:
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 提供「系统集成」页,只允许平台管理员人员账号操作:
- 腾讯云短信:SecretId/SecretKey(只写不回显)、SdkAppId、签名、绑定/通知模板 ID、地域、启用开关、发送测试短信;
- 微信网站应用:AppID、AppSecret(只写不回显)、回调地址、启用开关;
- 手机号绑定总开关;
- 秘密值使用 Fernet 加密后写入数据库,页面只显示“已配置/未配置”;
- 保存写审计,不返回完整秘密值。
角色边界:
users.role='admin'的人员账号是平台超级管理员;ADMIN_API_KEYS是环境 break-glass 管理密钥,可以应急管理,但没有人员身份、手机号和审计姓名,不能进「系统集成」配置页;- 账号 owner 不是平台超管,只能看自己业务账号的手机号掩码。
配置后如何验收
- 人员超管进入「系统集成」,保存腾讯云短信和微信网站应用配置;
- 点「运行自检」:检查密钥/模板/回调地址/管理员手机号是否齐全;
- 在账号安全绑定管理员手机号,点「发送测试短信」;
- 打开
/open/login,点「微信扫码登录」,确认授权、绑定和登录; - 未绑定微信扫码时,应提示先用账号密码登录后绑定,不应自动创建账号;
- 失败时进入「运行监控 → 错误与系统事件」,来源筛选「集成」,点「查看」→「复制排查包」,把排查包和截图发给研发。
排查包只包含时间、接口、故障编号、摘要、堆栈摘要和版本,不含 SecretKey、AppSecret、完整手机号或请求体。
腾讯云短信需先在控制台完成签名、模板报备;微信需先完成网站应用审核和回调域配置。
微信网站应用回调地址填写:
https://ai.banmahuanao.com/open/wechat/callback
微信后台的「授权回调域」填写 ai.banmahuanao.com。登录页在微信配置开启后显示「微信扫码登录」;未绑定账号扫码会提示先用账号密码登录后在「账号安全」绑定,不会自动创建业务账号。
七、调用与追踪
用量
支持:
- 最近 24 小时
- 最近 7 天
- 最近 30 天
展示:
- 调用
- 失败
- 平均耗时
- 应用数
- 每日调用量趋势
- 按日期明细
可导出 CSV。
request_id 追踪
在「调用与追踪」输入识别返回的 request_id,可以看:
- 调用状态
- 模型/版本
- 总耗时/推理耗时
- 检出数量和类别
- 复核进度
外部账号只能查看自己业务账号下应用产生的调用;查不到时先确认 request_id 是否属于当前账号。
八、异步任务
任务用于长耗时或需要回调的调用:
- 创建任务(URL/上传)
- 查询任务列表
- 查看任务详情
- 取消排队/运行中的任务
- 回调失败时重试
- 查看回调记录
重点字段:
| 字段 | 含义 |
|---|---|
| task_id | 任务 ID |
| status | queued / running / succeeded / failed / canceled |
| callback_status | none / pending / sent / failed |
| attempts | 已执行次数 |
| callback_attempts | 回调尝试次数 |
| result | 成功后的识别结果 |
| error | 失败原因 |
九、成员管理
owner 可以:
- 添加成员
- 调整 owner/member
- 重置成员密码
- 移除成员
规则:
- 最后一个 owner 不能降级或移除
- 普通成员只读
- 成员密码重置后原会话失效
- 不能移除自己
十、错误与排障
| 状态 | 常见原因 | 处理 |
|---|---|---|
| 401 | 密钥无效、过期、撤销;未登录 | 检查 X-API-Key;重新登录 |
| 403 | 应用停用、账号到期/停用、能力或 IP 不允许 | 看返回文案;联系平台运营 |
| 404 | request_id/任务不存在或不属于当前账号 | 确认 ID 和账号 |
| 409 | 任务已结束、回调不可重试、申请已处理 | 看任务/申请状态 |
| 413 | 图片或上传超过限制 | 压缩/换图 |
| 422 | 参数格式错误(模型、conf、字段) | 看字段说明 |
| 429 | 配额、并发或槽位繁忙 | 稍后重试或联系运营调整配额 |
| 500 | 服务内部错误 | 记录 incident_id,查看调用追踪 |
排障顺序:
- 看响应状态和
detail - 保存
request_id/incident_id - 到「调用与追踪」查 request_id
- 确认账号/应用/密钥/配额/IP
- 仍无法解决时提供 request_id、时间、应用 ID 和错误文案给平台运营
十一、安全与边界
- 密钥只显示一次,不要发到群聊或写进前端
- 回调密钥只用于验签,不要暴露
- 应用 ID 是公开标识,不是凭据
- 账号/应用停用、密钥撤销立即生效
- 开放平台仍按单组织/单租户部署,不做独立租户数据库
- 平台不承诺现场精度;精度以验收为准
- 不做公开注册、计费、SLA;需要商务开通
十二、常见问题
申请提交后多久能通过?
由平台运营审批,没有自动时限;用申请号 + 联系人查询状态。
审批通过后没有收到密码?
首个登录账号的临时密码只展示一次,由审批人/运营交付;审批通过后的弹窗支持一键复制(登录地址 /open/login + 账号 + 临时密码 + 改密提示),直接发给申请人即可;丢失后请联系运营或 owner 重置。
怎么修改自己的登录密码?
开放平台当前没有自助改密入口;请联系账号 owner 重置成员密码,或联系平台运营协助。人员账号在内部控制台右上角账号菜单可以自行修改密码。
为什么创建应用后没有可用模型?
可用模型由平台运营配置;默认不选表示全部,若被限制则只能使用授权模型。
为什么调用返回 429?
可能是每秒/每日配额、并发上限或推理槽位繁忙;看响应文案,必要时调整配额或重试。
为什么回调没有到?
看任务详情 callbacks:可能是无回调地址、签名失败、业务方返回非 2xx 或重试用尽。owner 可重试回调。
为什么外部追踪查不到?
只能查当前业务账号下应用产生的调用;跨账号不可见。
能修改可用模型/IP 白名单吗?
开放平台 owner 只能改应用名称、状态、回调地址;模型、能力、配额、IP 由平台运营配置。