AY-ROBOTSAI Teleoperation
Sign Up

API 参考

AY-Robots 的 REST API 位于 https://www.ay-robots.com/api 之下，双向都使用 JSON 进行通信。本页记录了身份验证方式、响应约定，以及每一个接口，并为您最可能以编程方式调用的路由提供完整的参数文档。

最后更新 2026-08-09

身份验证

除非在“公开”部分中列出，否则每个接口都需要身份验证。API 接受两种凭据形式，两者的传递方式相同：既可以作为仪表盘本身已经发送的会话 cookie，也可以作为带有 Bearer 令牌的 Authorization 请求头。

方式工作原理适用场景
浏览器会话您已登录账户的 Supabase 会话令牌，以 cookie 或 Bearer 令牌的形式发送仪表盘本身，以及在已认证的浏览器环境中进行的快速实验
API 密钥带有 ayr_live_ 前缀的密钥，在 /dashboard/settings 中创建，以 Bearer 令牌形式发送脚本、服务器、CI，以及任何不能依赖浏览器登录的场景
MCP位于 https://www.ay-robots.com/api/mcp 的托管 MCP 服务器（Streamable HTTP）使用 Model Context Protocol 的 LLM 代理和工具
bash
curl https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here'
使用 API 密钥进行身份验证

API 密钥在 /dashboard/settings 中创建和撤销。请像对待密码一样对待它们：将其保存在服务端，轮换时先创建替换密钥，再撤销旧密钥。如果您使用桌面 CLI，还可以通过命令 ay-robots mcp 将平台暴露为本地 MCP 服务器。

响应均为 JSON 格式。错误采用统一的结构：一个 JSON 对象，包含一个 error 字段，内容为人类可读的信息，并配以相应的 4xx 或 5xx 状态码。成功的响应会直接返回资源；少数接口会将列表包装在一个具名字段中，下方的示例会在相关之处展示这一点。

身份验证接口

账户和个人资料相关的基础接口。它们主要供仪表盘本身使用，但任何有效凭据都可以调用它们。

GET/api/auth/profileBearer 会话令牌或 API 密钥

返回已认证用户的个人资料。

POST/api/auth/profileBearer 会话令牌或 API 密钥

更新个人资料字段，例如显示名称和通知偏好设置。

POST/api/auth/syncBearer 会话令牌

将 Supabase 身份验证用户与平台用户记录进行同步。

GET/api/auth/check-onboardingBearer 会话令牌

报告已认证用户是否已完成入驻流程。

POST/api/auth/avatarBearer 会话令牌

为已认证用户上传新的头像图片。

客户接口

机器人所有者需要管理的一切：已注册的机器人、客户个人资料、数据集、发票，以及仪表盘统计数据。

GET/api/client/robotsBearer 会话令牌或 API 密钥（客户角色）

列出已认证客户注册的机器人，按最新排序，最多 50 条。时间戳采用 ISO 8601 格式；在机器人首次连接之前，last_online 和 last_heartbeat 均为 null。

Request
curl https://www.ay-robots.com/api/client/robots \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
[
  {
    "id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
    "name": "Lab SO-100",
    "robot_type": "SO-100",
    "status": "AVAILABLE",
    "control_url": "wss://robots.example.com/so100/control",
    "stream_url": "https://robots.example.com/so100/stream",
    "hardware_id": "board:local:usb-1",
    "last_online": "2026-08-09T10:12:00.000Z",
    "last_heartbeat": "2026-08-09T10:12:00.000Z",
    "total_hours": 12.5,
    "tags": ["lab"],
    "notes": null,
    "created_at": "2026-07-01T09:00:00.000Z"
  }
]
POST/api/client/robotsBearer 会话令牌或 API 密钥（客户角色）

注册一台新机器人并返回其 id。一个电机板硬件 id 只能属于一台机器人，发生冲突时会以状态码 409 拒绝。

GET/api/client/profileBearer 会话令牌或 API 密钥（客户角色）

返回已认证用户的客户个人资料。

PATCH/api/client/profileBearer 会话令牌或 API 密钥（客户角色）

更新客户个人资料字段。

GET/api/client/datasetsBearer 会话令牌或 API 密钥（客户角色）

列出该客户的云端数据集，包含回合数和文件大小。

GET/api/client/invoicesBearer 会话令牌或 API 密钥（客户角色）

列出该客户的月度发票。

GET/api/client/statsBearer 会话令牌或 API 密钥（客户角色）

返回客户仪表盘的使用统计数据。

操作员接口

操作员一侧的接口：个人资料与可用状态、认证、排班，以及收益统计数据。

GET/api/operator/profileBearer 会话令牌或 API 密钥（操作员角色）

返回已认证用户的操作员个人资料。

POST/api/operator/profileBearer 会话令牌或 API 密钥（操作员角色）

创建或更新操作员个人资料。

GET/api/operator/available-robotsBearer 会话令牌或 API 密钥（操作员角色）

列出当前可用且与该操作员认证相匹配的机器人。

GET/api/operator/certificationsBearer 会话令牌或 API 密钥（操作员角色）

列出该操作员的认证申请及其状态。

POST/api/operator/certificationsBearer 会话令牌或 API 密钥（操作员角色）

为某个机器人型号申请认证。

GET/api/operator/scheduleBearer 会话令牌或 API 密钥（操作员角色）

返回该操作员的每周可用时间安排。

POST/api/operator/scheduleBearer 会话令牌或 API 密钥（操作员角色）

更新每周可用时间安排。

GET/api/operator/availabilityBearer 会话令牌或 API 密钥（操作员角色）

返回该操作员当前的可用状态。

GET/api/operator/statsBearer 会话令牌或 API 密钥（操作员角色）

返回操作员仪表盘的收益和会话统计数据。

会话

会话是平台的核心资源：一个会话代表操作员与机器人之间一次连续的遥操作过程。会话状态会依次经过 PENDING、ACTIVE、PAUSED、COMPLETED 和 CANCELLED。

GET/api/sessionsBearer 会话令牌或 API 密钥

列出已认证用户的会话。操作员看到的是自己操作过的会话，客户看到的是自己机器人上发生的会话。两种视图的字段集略有不同：客户视图包含 episodes_collected 和 data_collected_mb，操作员视图包含 operator_earnings_cents。

NameInTypeDescription
statusquerystring可选。按会话状态筛选，例如 ACTIVE 或 COMPLETED。省略则列出全部。
limitquerynumber可选。分页大小，默认 50，最大 100。
offsetquerynumber可选。分页偏移量，默认 0。
Request
curl 'https://www.ay-robots.com/api/sessions?status=COMPLETED&limit=10' \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
{
  "sessions": [
    {
      "id": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
      "status": "COMPLETED",
      "started_at": "2026-08-08T14:00:12.000Z",
      "ended_at": "2026-08-08T14:47:31.000Z",
      "duration_minutes": 47,
      "client_charge_cents": 1175,
      "episodes_collected": 23,
      "data_collected_mb": 210.4,
      "rating": 5,
      "created_at": "2026-08-08T13:59:58.000Z",
      "robot_id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
      "robot_name": "Lab SO-100",
      "robot_type": "SO-100",
      "operator_name": "Jane D."
    }
  ]
}
POST/api/sessionsBearer 会话令牌或 API 密钥（操作员角色）

在一台可用的机器人上启动一次遥操作会话。需要操作员角色：客户无法启动会话。一名操作员同一时间最多只能持有一个 ACTIVE 或 PAUSED 会话，且该机器人当前状态必须为 AVAILABLE。立即启动时，机器人会切换为 IN_SESSION，并通知客户。

NameInTypeDescription
robotIdbodystring必需。要操作的机器人 id。该机器人必须处于 AVAILABLE 状态。
operatorIdbodystring可选。显式指定操作员 id，默认为已认证的操作员。
scheduledForbodystring (ISO 8601)可选。将会话安排在未来某个时间，而不是立即启动。
Request
curl -X POST https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"robotId": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11"}'
Response
{
  "sessionId": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
  "status": "ACTIVE"
}
GET/api/sessions/[id]Bearer 会话令牌或 API 密钥

返回单个会话及其详细信息。

PATCH/api/sessions/[id]Bearer 会话令牌或 API 密钥

更新会话生命周期：暂停、恢复、结束及相关操作。

POST/api/sessions/[id]/extendBearer 会话令牌或 API 密钥（客户，会话所有者）

申请延长会话。只有拥有该会话的客户可以调用此接口，且会话必须处于 ACTIVE 状态。该请求会作为一条会话事件被记录，操作员会收到通知，延长操作本身在操作员响应后才会生效。

NameInTypeDescription
idpathstring会话 id。
additionalMinutesbodynumber申请延长的时长，以分钟为单位。
Request
curl -X POST https://www.ay-robots.com/api/sessions/6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30/extend \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"additionalMinutes": 30}'
Response
{
  "message": "Extension request sent to operator"
}
GET/api/sessions/[id]/messagesBearer 会话令牌或 API 密钥

列出某个会话的聊天消息。

POST/api/sessions/[id]/messagesBearer 会话令牌或 API 密钥

在会话中发送一条聊天消息。

POST/api/sessions/[id]/rateBearer 会话令牌或 API 密钥（客户）

为一次已完成的会话打分，评分范围为 1 到 5 星，可附带可选的评论。

POST/api/sessions/exportBearer 会话令牌或 API 密钥

导出会话数据。

支付

所有资金流转都通过 Stripe 进行。客户账单使用带有已保存支付方式的 Stripe 客户对象；操作员收益结算使用 Stripe Connect。平台本身从不存储银行卡或银行账户数据。

POST/api/stripe/customerBearer 会话令牌（客户角色）

创建或返回用于客户账单的 Stripe 客户对象。

GET/api/stripe/connectBearer 会话令牌（操作员角色）

返回该操作员 Stripe Connect 账户的状态。

POST/api/stripe/connectBearer 会话令牌（操作员角色）

启动用于操作员收益结算的 Stripe Connect 入驻流程。

POST/api/stripe/setup-intentBearer 会话令牌（客户角色）

创建一个用于保存支付方式的 Stripe SetupIntent。

POST/api/stripe/portalBearer 会话令牌（客户角色）

创建一个 Stripe 账单门户会话，用于管理支付方式和发票。

GET/api/stripe/payoutBearer 会话令牌（操作员角色）

返回已认证操作员的收益结算信息。

POST/api/stripe/payoutBearer 会话令牌（操作员角色）

申请提取已累积的收益。最低收益结算金额为 10.00 EUR。

POST/api/stripe/webhookStripe Webhook 签名

接收 Stripe 的 Webhook 事件。由 Stripe 调用，而非由 API 客户端调用。

公开接口

这些接口不需要身份验证。可以安全地从监控系统、营销页面或状态探测中调用它们。

GET/api/health

API 及其数据库连接的健康检查。两者均正常时返回 200；如果数据库检查失败，会以相同的结构返回，status 和 db 设为 error，HTTP 状态码为 503。

Request
curl https://www.ay-robots.com/api/health
Response
{
  "status": "ok",
  "db": "ok",
  "timestamp": "2026-08-09T10:12:00.000Z"
}
GET/api/robots/[id]

返回某个受支持机器人型号的公开信息。

GET/api/public/pricing

返回当前的公开定价套餐。

POST/api/contact

提交一条联系表单消息。消息会先被存储，然后通过邮件送达，因此临时的邮件故障不会导致消息丢失：在这种情况下，响应会报告 stored 为 true、delivered 为 false，送达会在运维层面重试。

NameInTypeDescription
namebodystring必需。您的姓名。
emailbodystring必需。用于回复的有效邮箱地址。
categorybodystring必需。取值为以下之一：General Inquiry、Bug Report、Feature Request、Sales & Pricing、Partnership、Career/Jobs、Technical Support、Billing & Payments、Press & Media、Other。
subjectbodystring必需。简短的主题行。
messagebodystring必需。消息正文。
Request
curl -X POST https://www.ay-robots.com/api/contact \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "category": "Technical Support",
    "subject": "SO-100 pairing question",
    "message": "My arm shows as offline after pairing."
  }'
Response
{
  "success": true,
  "message": "Message sent successfully",
  "id": "b1f2c3d4-0000-0000-0000-000000000000",
  "stored": true,
  "delivered": true
}
POST/api/robot-request

为平台尚不支持的机器人型号申请支持。

GET/api/stats

返回平台的公开统计数据。

相关页面
Security

了解 AY-Robots 如何保护账户和实时机器人控制的安全：Supabase 身份验证、角色权限模型、API 密钥管理、会话安全机制、审计日志，以及数据加密方式。

Sessions

了解 AY-Robots 会话的运作方式：从 PENDING 到 COMPLETED 的完整生命周期、每一种活动事件的含义、会话聊天、评分机制、延长会话，以及训练数据的产生过程。

上一页
Supported robots
下一页
Billing & payments