设备推送 Gateway API 接口文档
概述
npcid 自动路由到正确的 TCP Pod；设备离线时消息进入队列，上线后自动投递。https://adventists.cn/tcphub/api鉴权方式
| Header | 类型 | 必填 | 说明 |
|---|---|---|---|
api-key | string | 是 | 32 位 API 密钥 |
org-id | string | 是 | 组织 ID（合作伙伴为 6 位；平台内部账号见权限说明） |
注意：Header 名称使用连字符（ api-key、org-id），不要使用下划线。
401：{
"message": "Invalid API KEY or ORG ID"
}权限说明
| 调用方 | org-id 格式 | npcid 权 限 |
|---|---|---|
| 合作伙伴 | 6 位（与 AnyoneAI 注册 org 一致） | 只能推送 npcid 前 6 位与 org-id 一致的设备 |
| 平台内部（如 Sophon） | 由平台分配 | 可推送任意 npcid |
403：{
"ok": false,
"error": "Cannot push to NPC belonging to another org"
}接口一览
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/push | 推送消息（推荐） |
| POST | /api/speak | 语音播报（兼容旧接口） |
| GET | /api/tasks/{task_id} | 查询任务状态 |
推送消息
POST /api/push请求体
{
"npcid": "ABC123your-npc-id-here",
"type": "speak",
"payload": {
"text": "你好，这是一条测试消息"
},
"source": "my-app",
"callback_url": "https://example.com/webhook",
"priority": "normal",
"task_id": "optional-external-id"
}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| npcid | string | 是 | 目标设备/角色 ID |
| type | string | 否 | 推送类型，默认 speak；可选：speak / text / info / image / agent_turn / choice |
| payload | object | 条件 | 推送内容；speak/text/info 需含 text；image 需含 url |
| source | string | 否 | 来源标识 |
| callback_url | string | 否 | 任务终态 webhook 地址 |
| priority | string | 否 | 队列优先级：urgent / high / normal / low |
| task_id | string | 否 | 外部任务 ID（不传则自动生成 ） |
推送类型（type）
| type | TCP 帧 | payload 必填 | 离线排队 | 说明 |
|---|---|---|---|---|
speak | AUDIO via TTS | text | 是 | 语音播报，经 TTS 转为音频流下发 |
text | TEXT(0x04) + END_FRAME | text | 是 | 纯文字显示，不口播 |
info | STATUS(0x05) ##INFO:xxx | text | 是 | 系统通知/提示，不口播 |
image | IMAGE(0x0a) | url | 否 | 图片即时推送，设备不在线返回 404 |
agent_turn | 无（回调专用） | 自定义 | 是 | 用于 Agent 回合触发，TCP 侧待实现 |
choice | 无（回调专用） | 自定义 | 是 | 用于选项推送，TCP 侧待实现 |
speak / text / info：设备离线时自动入队，上线后投递；text 和 info 下发的均为纯展示帧，不触发 TTSimage：即时投递，不排队；服务器根据设备认证时声明的 resolution 自动追加 TOS 缩放参数agent_turn / choice：创建任务记录供 webhook 回调，TCP 侧下发尚未实现成功响应
{
"ok": true,
"task_id": "a1b2c3d4",
"status": "delivered",
"routed_to": "10.42.0.15:3007"
}{
"ok": true,
"task_id": "a1b2c3d4",
"status": "queued",
"queue_position": 1,
"online_npcids": 205
}错误响应
{
"ok": false,
"error": "Missing npcid"
}{
"message": "Invalid API KEY or ORG ID"
}{
"ok": false,
"error": "Cannot push to NPC belonging to another org"
}{
"ok": false,
"task_id": "a1b2c3d4",
"status": "failed",
"error": "Failed to reach pod: ...",
"routed_to": "10.42.0.15:3007"
}cURL 示例
查询任务状态
GET /api/tasks/{task_id}路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_id | string | 是 | 推送返回的 task_id |
成功响应（200）
{
"ok": true,
"task": {
"task_id": "a1b2c3d4",
"npcid": "ABC123your-npc-id",
"org_id": "ABC123",
"type": "speak",
"status": "delivered",
"payload": {"text": "你好"},
"created_at": 1717200000.0,
"updated_at": 1717200001.0,
"routed_to": "10.42.0.15:3007",
"result": null
}
}错误响应
{
"ok": false,
"error": "Task not found"
}Webhook 回调
callback_url，任务进入终态（delivered / completed / failed 等）时 Gateway 会 POST 回调：请求 Header
| Header | 说明 |
|---|---|
Content-Type | application/json |
X-Gateway-Signature | HMAC-SHA256 签名（hex），密钥为 Gateway 内部 secret |
回调 Body 示例
{
"task_id": "a1b2c3d4",
"status": "completed",
"npcid": "ABC123your-npc-id",
"type": "agent_turn",
"source": "my-app",
"routed_to": "10.42.0.15:3007",
"result": {"answer": "ok"},
"event": "completed"
}验签方式
任务状态说明
| status | 说明 |
|---|---|
accepted | 已接受 |
queued | 设备离线/忙碌，排队中 |
routed | 已路由到 TCP Pod |
delivered | 投递成功 |
completed | 任务完成 |
failed | 投递失败 |
timeout | 超时 |
cancelled | 已取消 |
常见问题
ask/init_npc 等接口使用相同的凭证。npcid 的前 6 位等于组织的 org-id。例如 org-id 为 ABC123 时，合法 npcid 形如 ABC123xxxxxxxx...。修改于 2026-06-03 06:29:54