API Reference

润吧云 API 文档

通过 RESTful API 调用润吧云模型广场中的 AI 模型，实现图像识别、视频分析等智能能力的快速集成。

获取 API Key

创建密钥后即可调用

发起第一次调用

一行 curl 即可测试

查看使用记录

用量、费用一目了然

快速开始

三步完成 API 集成：注册账号 → 创建 API Key → 发起请求。

注册并登录

前往注册页面创建账号。

获取 API Key

在密钥管理页面创建一个密钥，格式为 sk-...。

调用 API

使用下方示例即可发起请求。

curl

curl -X POST https://api.runba.cloud/api/v1/predict \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fire-false-alarm",
    "image_url": "https://your-oss.com/image.jpg"
  }'

认证方式

所有 API 请求必须携带有效的 API Key 进行身份认证。在请求头中使用 Bearer Token 方式传递：

http

Authorization: Bearer sk-your-api-key

安全提示

请勿将 API Key 硬编码在前端代码或公开仓库中。建议使用环境变量或密钥管理服务存储。

可用模型

以下模型已部署上线，可通过 API 直接调用。在请求中使用 model 字段指定模型 slug。

模型 slug	名称	分类	单价
`helmet-false-alarm`	安全帽误报识别	视频智能分析	¥0.02/次
`fire-false-alarm`	明火误报识别	视频智能分析	¥0.02/次
`smoking-detection`	抽烟行为检测	视频智能分析	¥0.02/次
`phone-call-detection`	接打电话检测	视频智能分析	¥0.02/次
`uniform-classification`	工服便装分类	视频智能分析	¥0.02/次
`smoke-detection`	烟雾检测	视频智能分析	¥0.02/次
`area-intrusion-filter`	区域入侵误报过滤	视频智能分析	¥0.02/次

图像预测接口

POST/api/v1/predict

通用图像预测接口。传入模型 slug 和图片 URL，网关自动路由到对应的后端推理服务，并完成计费和记录。

请求参数

参数	类型	必填	说明
`model`	string	必填	模型 slug，见上方模型列表
`image_url`	string	可选	图片 URL（视觉类模型必传）
`data`	object	可选	JSON 数据输入（工艺/设备/质量类模型）

请求示例

curl

curl -X POST https://api.runba.cloud/api/v1/predict \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "helmet-false-alarm",
    "image_url": "https://your-oss.com/alarm-image.jpg"
  }'

Python 示例

python

import requests

response = requests.post(
    "https://api.runba.cloud/api/v1/predict",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "helmet-false-alarm",
        "image_url": "https://your-oss.com/alarm-image.jpg",
    },
)
result = response.json()
print(result)

返回示例

json

{
  "success": true,
  "model": "helmet-false-alarm",
  "prediction": {
    "label": "false_alarm",
    "label_cn": "误报",
    "confidence": 0.8765,
    "is_real_alarm": false,
    "persons_detected": 2,
    "person_results": [...],
    "inference_time_ms": 232.15
  },
  "usage": {
    "duration_ms": 350,
    "cost_cents": 2
  }
}

返回字段说明

字段	类型	说明
`success`	boolean	请求是否成功
`model`	string	调用的模型 slug
`prediction.label`	string	预测标签（英文）
`prediction.label_cn`	string	预测标签（中文）
`prediction.confidence`	number	置信度 (0~1)
`prediction.is_real_alarm`	boolean	是否为真实报警
`usage.duration_ms`	number	请求耗时（毫秒）
`usage.cost_cents`	number	本次调用费用（分）

Chat Completions（OpenAI 兼容）

POST/api/v1/chat/completions

兼容 OpenAI Chat Completions 格式的接口，支持流式（stream）和非流式输出。适用于对话类 Agent 模型。

请求示例

curl

curl -X POST https://api.runba.cloud/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-slug",
    "messages": [
      {"role": "system", "content": "你是一个工艺优化助手。"},
      {"role": "user", "content": "请分析当前报警数据。"}
    ],
    "max_tokens": 2048,
    "temperature": 0.7,
    "stream": false
  }'

Python（OpenAI SDK 兼容）

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.runba.cloud/api/v1",
)

response = client.chat.completions.create(
    model="your-model-slug",
    messages=[
        {"role": "user", "content": "分析一下最近的报警趋势"},
    ],
    max_tokens=2048,
)
print(response.choices[0].message.content)

错误码

API 遵循标准 HTTP 状态码，错误响应包含统一的 JSON 结构。

HTTP 状态码	错误码	说明
401	`invalid_api_key`	API Key 无效或缺失
402	`insufficient_balance`	余额不足，请充值
403	`service_not_allowed`	API Key 无权访问该模型
400	`model_not_found`	模型不存在或已下线
429	`rate_limit_exceeded`	请求频率超限
503	`upstream_unreachable`	上游推理服务不可用
504	`upstream_timeout`	上游服务响应超时

错误响应格式

json

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "余额不足，请充值后重试",
    "param": null
  }
}

使用记录

每次 API 调用都会自动记录用量和费用。你可以通过以下方式查看使用记录：

控制台查看

登录后在「我的账户 → 使用记录」页面，可查看每日用量图表、调用次数和费用明细。

API 查询

也可以通过 API 接口获取使用数据，用于集成到你的监控系统中。

用量查询接口

GET/api/v1/usage/daily?days=30

curl

curl https://api.runba.cloud/api/v1/usage/daily?days=30 \
  -H "Authorization: Bearer sk-your-api-key"

json

{
  "items": [
    {
      "date": "2026-06-01",
      "total_calls": 156,
      "total_tokens": 0,
      "total_cost_cents": 312
    },
    {
      "date": "2026-06-02",
      "total_calls": 203,
      "total_tokens": 0,
      "total_cost_cents": 406
    }
  ],
  "total_calls": 359,
  "total_tokens": 0,
  "total_cost_cents": 718
}

本月概要

GET/api/v1/usage/summary

curl

curl https://api.runba.cloud/api/v1/usage/summary \
  -H "Authorization: Bearer sk-your-api-key"

json

{
  "total_calls": 1250,
  "total_tokens": 0,
  "total_cost_cents": 2500,
  "active_keys": 2
}