API 集成

Open4X API 地址：

https://api.open4x.com

应用服务统一挂载在：

/v1/apps

鉴权

API Key

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

X-API-Key: sk_xxx

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

JWT

控制台登录态使用 JWT：

Authorization: Bearer <token>

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

注册和登录

POST /auth/register
POST /auth/login
POST /auth/refresh
POST /auth/logout

登录返回 token 和 refresh_token。refresh token 会轮换，旧 token 使用一次后失效。

推荐 Scope

Scope	能力
bot:send	发送 bot 消息和回复。
bot:session:create	创建 Widget 短期 Session。
bot:events:read	读取 Widget 会话增量事件。
file:read	读取或下载文件。
push:send	发送 Webhook Push 消息。
tron:lease	创建和查询 TRON 能量租赁订单。
jobs:read	查询当前租户的异步 Job 状态。
ai:invoke	调用 AI chat、streaming 和 embeddings。
socialops:write	写入 SocialOps webhook 事件。
socialops:read	读取 SocialOps inbox 线程和消息。
*	受控场景下允许全部 API Key scope。

API Key 的 scope 为空时，受 scope 保护的接口会拒绝请求。不要依赖“空 scope 等于无限权限”的旧行为。

API Key 策略

创建 Key 时可以限制服务 alias、来源 IP/CIDR、UTC 每日额度和过期时间：

{
  "name": "production-ai",
  "scopes": ["ai:invoke"],
  "service_aliases": ["ai-model:qwen122"],
  "allowed_ips": ["203.0.113.0/24"],
  "daily_quota": 1000,
  "rate_limit_per_minute": 60,
  "concurrency_limit": 4,
  "expires_at": "2026-12-31T00:00:00Z"
}

来源校验只使用 Cloudflare 的 cf-connecting-ip，不信任客户端提交的转发头。每日额度采用原子更新；Key 过期后会自动停用并写入生命周期审计。

标准错误

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

{
  "error": "Insufficient balance"
}

当前接口仍以平铺错误为主，客户端应兼容附加字段：

{
  "error": "Insufficient balance",
  "pricing": {"cost": 0.01}
}

结构化 error.code 响应属于后续统一方向，不应假设每个接口当前都返回该字段。

常见状态码：

HTTP	Code	含义
400	invalid_request	请求体或参数错误。
401	unauthorized	缺少或无效凭据。
402	insufficient_balance	余额不足。
403	forbidden	缺少权限。
404	not_found	资源不存在。
409	冲突	超出 max_cost、报价过期、或 AI 幂等 Key 重复。
422	业务校验失败	由具体服务定义。
429	触发限流	需要退避重试。
502	上游失败	provider 或绑定服务失败。

服务 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
OpenAI-compatible AI	GET /v1/apps/ai/:alias/v1/models、POST /v1/apps/ai/:alias/v1/chat/completions、POST /v1/apps/ai/:alias/v1/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
异步 Job 列表	GET /v1/jobs
异步 Job 状态	GET /v1/jobs/:id
SocialOps Webhook	POST /v1/apps/socialops/:alias/webhook/:provider
SocialOps Provider 能力目录	GET /v1/apps/socialops/providers
SocialOps Inbox	GET /v1/apps/socialops/:alias/inbox
SocialOps 线程列表	GET /v1/apps/socialops/:alias/threads
SocialOps 线程消息	GET /v1/apps/socialops/:alias/threads/:thread_id/messages
SocialOps 回复队列	POST /v1/apps/socialops/:alias/threads/:thread_id/replies
文件上传	PUT /v1/apps/file/upload
文件列表	GET /v1/apps/file/list
文件下载/分享	GET /v1/apps/file/download/*、GET /v1/apps/file/share/*
Bot 发送	POST /v1/apps/bot
Bot 聊天/消息	GET /v1/apps/bot/chats、GET /v1/apps/bot/chats/:chatId/messages
Bot 回复	POST /v1/apps/bot/messages/reply
Bot 交互	`GET
Widget Session	POST /v1/apps/bot/widget/auth、POST /v1/apps/bot/widget/refresh、POST /v1/apps/bot/widget/revoke
Widget 聚合事件	GET /v1/apps/bot/widget/events?cursor=...&limit=100

创建 API Key 和服务

控制台接口使用 JWT：

POST /console/keys
POST /console/keys/{id}/rotate
DELETE /console/keys/{id}
POST /console/services

创建 API Key：

curl -X POST https://api.open4x.com/console/keys \
  -H "Authorization: Bearer $OPEN4X_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-ai","scopes":["ai:invoke"],"service_aliases":["ai-model:qwen122"],"allowed_ips":["203.0.113.0/24"],"daily_quota":1000}'

明文 Key 只返回一次。轮换接口会返回替代 Key，并立即让旧 secret 失效。创建、轮换、撤销、过期、策略拒绝和额度事件会进入审计，但不会保存完整 secret。

每个响应都会带 X-Request-ID。AI 用量记录使用网关 request ID，而不是上游 provider 的 request ID。租户管理员可以使用 GET /console/requests/:request_id 查询脱敏的 AI 用量和 API Key 审计元数据；不会返回 prompt、回答或 secret。

异步 Job 和回调

TRON 租赁创建接口会返回 job_id。API Key 需要 jobs:read scope：

GET /v1/jobs/job_xxx

统一状态为 pending、running、succeeded、failed、canceled、expired。创建租赁时可以传 HTTPS callback_url 和 16–256 位 callback_secret。job.updated 回调使用 X-Open4X-Signature: sha256=<HMAC-SHA256> 签名，失败后指数退避，最多重试 8 次。沙盒不会调用外部回调。

创建 AI 服务实例：

curl -X POST https://api.open4x.com/console/services \
  -H "Authorization: Bearer $OPEN4X_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "ai-model",
    "alias": "qwen122",
    "status": "active",
    "config": {
      "provider": "openai-compatible",
      "mode": "byok",
      "base_url": "https://model.example.com/v1",
      "default_model": "my-model",
      "api_key": "provider-key",
      "max_tokens_per_request": 1024,
      "max_cost_per_request": 0.05
    }
  }'

服务实例也可以使用 connected_account_id 引用 Connections 中的加密凭据。服务列表会自动脱敏。

AI 请求和计费响应头

curl -X POST https://api.open4x.com/v1/apps/ai/qwen122/chat \
  -H "X-API-Key: sk_xxx" \
  -H "Idempotency-Key: ai-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "messages":[{"role":"user","content":"用三句话解释 webhook。"}],
    "max_tokens":300,
    "max_cost":0.05
  }'

messages 必须是非空数组，model 省略时使用服务的 default_model。非流式响应会返回：

X-OpenEdge-Estimated-Cost: 0.0005
X-OpenEdge-Final-Cost: 0.0005
X-OpenEdge-Total-Tokens: 120

流式响应先返回预估费用，流结束后结算；当前不会把最终费用追加到已经建立的 SSE 响应头中。Idempotency-Key 只允许 1–128 个 A-Z a-z 0-9 . _ : - 字符。

Webhook Push

curl -X POST https://api.open4x.com/v1/apps/webhook-push/ops/send \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Order Paid","text":"订单 10001 已支付"}'

全部成功返回 200，部分 target 成功返回 207，全部失败返回 502，余额不足返回 402。每个 target 可以独立启用；Telegram target 必须有 Bot Token 或 Telegram connection，并配置 chat_id。

SocialOps

入站事件和回复接口分别要求 socialops:write 和 socialops:read：

curl -X POST https://api.open4x.com/v1/apps/socialops/support/webhook/generic-webhook \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_1","thread_id":"conversation-42","subject":"客户咨询","text":"请问什么时候发货？"}'

成功返回 202 并返回 thread_id、message_id。重复事件会返回 duplicate: true。回复接口返回 202 只代表已写入出站 action；第三方平台是否送达需要查询 action 或平台回执。

TRON 能量租赁

能量范围是 1000–5000000，租赁时长范围是 300–86400 秒。推荐先报价，再使用 quote_id 和 max_cost 创建订单。创建订单通常返回 202 pending，只有完成 provider 履约和链上校验后才代表成功；Idempotency-Key 可以避免同一租户对相同租赁参数重复扣费；沙盒返回 dry_run，不会扣余额或创建真实订单。

Widget 和文件

Widget 使用独立的 widget session JWT，创建路径为：

POST /v1/apps/bot/widget/auth
POST /v1/apps/bot/widget/token

文件公开下载和分享路径为：

GET /v1/apps/file/download/*
GET /v1/apps/file/share/*

文件上传和列表接口为 PUT /v1/apps/file/upload 与 GET /v1/apps/file/list；API Key 需要 file:read scope。标准上传使用原始字节流，并可通过 x-filename、x-expires-in、x-max-downloads 请求头设置文件信息和限制；为兼容旧客户端，上传也接受 POST。

稳定版 Bot API 已覆盖 /v1/apps/bot/* 下的聊天记录、回复、消息编辑/删除、文件消息、交互、动作和主发送接口；API Key 需要 bot:send。Widget、Webhook 和 WebSocket 属于独立的会话/供应商协议，仍在各自服务指南中说明。

OpenAPI 合约

可下载版本化的 OpenAPI 3.1 合约，其中包含网关、AI、Webhook Push、TRON、SocialOps、Bot 和 File 接口，可直接导入 Swagger UI、Postman 或 SDK 生成器。Widget、Webhook 和 WebSocket 会话协议使用供应商/升级专用鉴权，因此暂不与这些稳定 REST 接口混在同一组 schema 中。

健康检查

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

预期响应：

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