OMI API 文档

Appearance

API 参考 ​

OMI 玩具车远程控制平台提供完整的 RESTful API，遵循 RESTful 设计规范，支持第三方应用快速集成。所有 API 均使用 JSON 格式进行数据交换。

基础地址 ​

OMI 平台提供以下基础地址，请根据您的网络情况选择合适的地址：

环境地址
开发环境http://182.254.182.254:9090
生产环境http://omiok.cn

生产环境优先

建议在生产环境中使用 http://omiok.cn，该地址提供更稳定的服务。

认证方式 ​

所有 API 调用（除了 获取Token 接口外）都需要在请求头中携带 Token 进行身份认证。

请求头格式 ​

在 HTTP 请求头中添加 token 字段：

http
token: <your_access_token>

完整请求示例 ​

javascript
fetch('http://omiok.cn/device/ctrlUrl?deviceSn=TOY_CAR_001', {
  headers: {
    'token': 'your_access_token_here'
  }
})

Token 有效期

Token 有效期为 3 小时，过期后需要重新调用 获取Token 接口获取新的 Token。

建议在 Token 过期前（如提前 5 分钟）自动刷新，避免业务中断。

接口列表 ​

认证接口 ​

接口说明
获取 Token获取访问令牌，用于后续 API 调用的身份认证

设备管理接口 ​

接口说明
获取控制地址获取玩具车远程控制面板地址，支持自定义控制时长
设备列表查询设备列表，支持分页、筛选和状态查询

接口调用顺序

建议按照 认证接口 → 设备列表 → 获取控制地址 的顺序进行调用，确保设备可用后再发起控制。

通用响应格式 ​

所有接口都采用统一的 JSON 响应格式，便于开发和调试。

成功响应示例 ​

json
{
  "status": 0,
  "desc": "操作成功！",
  "time": 1640995200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

失败响应示例 ​

json
{
  "status": 1,
  "desc": "设备正在控制中！",
  "time": 1640995200,
  "data": null
}

字段说明 ​

字段名类型必选说明
statusinteger是响应状态码：0 表示成功，非 0 表示失败
descstring是响应描述信息，包含错误提示或成功信息
timeinteger是响应时间戳（Unix 时间戳）
dataobject否响应数据，成功时包含业务数据，失败时通常为 null

状态码说明

  • status = 0：请求成功，可以正常处理返回的数据
  • status != 0：请求失败，需要根据 desc 字段的提示信息进行处理

错误处理 ​

在 API 调用过程中，可能会遇到各种错误情况，OMI 平台提供详细的错误信息帮助您快速定位和解决问题。

常见错误类型 ​

  • 认证错误：Token 无效、过期或缺失
  • 参数错误：请求参数格式错误或缺失必填参数
  • 业务错误：设备不存在、设备被占用等业务逻辑错误
  • 系统错误：服务器内部错误，需要重试或联系技术支持

详细错误码

参考 错误处理指南 了解完整的错误码列表和处理最佳实践。

快速集成流程 ​

按照以下步骤快速集成 OMI API：

  1. 获取访问凭证 - 调用 /app/token 获取访问 Token
  2. 查询设备列表 - 使用 Token 调用 /device/openList 查询可用设备
  3. 获取控制地址 - 调用 /device/ctrlUrl 获取控制面板 URL
  4. 启动远程控制 - 将控制面板 URL 嵌入您的应用或直接打开

完整示例代码 ​

查看 快速开始指南 获取详细的集成步骤和完整代码示例。

重要提示

在调用 /device/ctrlUrl 前，建议先通过 /device/openList 查询设备的 useStatus 状态，确保设备空闲可用。

OMI

Copyright © 2025 OMI 平台