外部接入：第一次 API 对话（预览）

用途#

外部接入让业务后端通过 API 或 Webhook 调用 Onevium 助手。本页针对 1.1.23-beta.7 开发预览，不属于正式版 1.1.22；真实公网与生产业务验收尚未完成。

开始前#

准备可用预览环境。在「外部接入」创建应用、绑定助手，完成能力验证并发布助手，然后取得接入地址、App Key 和 endpoint ID。这里“发布助手”不是发布桌面正式版本。

默认使用内置接入；公网和 Docker 为可选项。App Key 只放业务后端，subject 来自已认证业务用户，不能信任浏览器传值。不要公开 Onevium 原管理端口。

第一次操作#

1. 在测试后端设置 GATEWAY_URL 为界面显示的接入地址、APP_KEY 为应用密钥。将示例 endpoint 替换成真实 ID。创建会话：

curl "$GATEWAY_URL/api/v1/conversations" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-create-001' \
  -H 'Content-Type: application/json' \
  --data '{"endpoint_id":"YOUR_ENDPOINT_ID","conversation_key":"docs-demo"}'

2. 把返回的会话 ID 保存为 CONVERSATION_ID。向新会话发送消息：

curl "$GATEWAY_URL/api/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'X-Onevium-Subject: docs-test-user' \
  -H 'Idempotency-Key: docs-message-001' \
  -H 'Content-Type: application/json' \
  --data '{"expected_generation":1,"input":{"text":"只回复：连接成功"}}'

3. 使用返回的 run_id，携带相同身份请求 GET /api/v1/runs/:run_id，直到取得实际终态和结果。202 只表示已接纳，不表示已完成。
4. 再发送一次时使用新幂等键；同一次网络重试必须保持原键与正文。重开上下文后使用新的实际 generation，不能一直填写 1。

确认成功#

业务会话、Onevium 执行和 Run 结果对应同一次请求。SSE 断开只停止观察，不取消任务；停止或 reset 应查询 operation 确认。内置模式随电脑休眠或关闭而不能接收新请求。

常见问题#

• 401/403：检查 App Key、scope 和助手授权。
• 409：检查 generation、忙碌状态及幂等键是否被用于不同正文。
• 已接纳但未完成：查看设备状态和审批，不要重新提交制造新执行。

接下来#

Webhook 使用独立签名和事件去重；结果回调是另一条投递链，只有目标返回 2xx 才确认送达。先完成上述内置流程，再安排 Docker、真实 TLS/SSH 与业务环境验收。相关入口见渠道，授权边界见权限。