API 集成

OpenEdge 生产 API：

https://api.open4x.com

应用服务统一挂载在：

/v1/apps

鉴权

API Key

服务端集成建议使用 API Key：

X-API-Key: sk_xxx

API Key 只展示一次，平台保存哈希。

JWT

控制台登录态使用 JWT：

Authorization: Bearer <token>

不要把 JWT 写入长期运行的生产服务。

推荐 Scope

Scope	能力
bot:send	发送 bot 消息和回复。
file:read	读取或下载文件。
file:write	上传或修改文件。
push:send	发送 Webhook Push 消息。
tron:lease	创建和查询 TRON 能量租赁订单。
ai:invoke	调用 AI chat、streaming 和 embeddings。
socialops:write	写入 SocialOps webhook 事件。
socialops:read	读取 SocialOps inbox 线程和消息。

标准错误

部分现有接口仍返回简单错误结构：

{
  "error": "Insufficient balance"
}

新接口建议逐步统一为结构化错误：

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "request_id": "req_xxx"
  }
}

推荐错误码：

HTTP	Code	含义
400	invalid_request	请求体或参数错误。
401	unauthorized	缺少或无效凭据。
402	insufficient_balance	余额不足。
403	forbidden	缺少权限。
404	not_found	资源不存在。
409	cost_limit_exceeded	超出 max_cost 或报价限制。
422	verification_failed	业务校验失败。
429	rate_limit_exceeded	触发限流或预算限制。
502	upstream_failed	上游服务失败。

服务 Endpoint

服务	Endpoint
AI Chat	POST /v1/apps/ai/:alias/chat
AI Streaming	POST /v1/apps/ai/:alias/chat/stream
AI Embeddings	POST /v1/apps/ai/:alias/embeddings
Webhook Push	POST /v1/apps/webhook-push/:alias/send
TRON 报价	POST /v1/apps/tron/quote
TRON 租赁	POST /v1/apps/tron/lease
TRON 订单列表	GET /v1/apps/tron/leases
TRON 订单详情	GET /v1/apps/tron/leases/:id
SocialOps Webhook	POST /v1/apps/socialops/:alias/webhook/:provider
SocialOps Inbox	GET /v1/apps/socialops/:alias/inbox
SocialOps 线程消息	GET /v1/apps/socialops/:alias/threads/:thread_id/messages
SocialOps 回复队列	POST /v1/apps/socialops/:alias/threads/:thread_id/replies
文件服务	/v1/apps/file/*
机器人服务	/v1/apps/bot/*

健康检查

curl https://api.open4x.com/health

预期响应：

{
  "status": "ok",
  "db": "ok",
  "ts": "2026-06-19T14:48:46.146Z"
}