Embedded 自助服务 API

终端使用 token exchange 返回的短期 Bearer 令牌访问固定 Application 下的 /api/v1/apps/{app}/users/me/*。不要让终端提交任意用户 ID，也不要把 AppClient secret 用在这些请求中。

能力	方法与路径
当前权益	GET /api/v1/apps/{app}/users/me/entitlements
余额	GET /api/v1/apps/{app}/users/me/wallet
交易记录	GET /api/v1/apps/{app}/users/me/transactions
用量	GET /api/v1/apps/{app}/users/me/usage
订单	GET/POST /api/v1/apps/{app}/users/me/orders
个人账单	GET /api/v1/apps/{app}/users/me/statements
支持工单	/api/v1/apps/{app}/users/me/support/tickets*

创建订单时为同一次业务操作复用 UUID Idempotency-Key。返回的支付意图不是付款成功凭证；最终状态以随后查询到的订单结果为准。

游标是不可解析的不透明字符串。把 next_cursor 原样传回 cursor，并遵守 has_more。金额、Credits、余额和费率使用十进制字符串；展示时保留服务端精度，计算时使用十进制定点库。

数据 API 使用相同短期 Bearer 令牌时，可调用已授权的 /v1/chat/completions、/v1/balance 与 /v1/usage 等入口。可用能力以当前权益与 /v1/models 返回结果为准。

SDK 0.3.0 补充

createOrder 返回的 mode 可以是 redirect、qr 或 client_sdk。最后一种模式使用 client_params（Swift/Kotlin 为 clientParams）初始化对应支付组件；这些参数有时效，不应记录或持久化。付款状态仍需查询订单确认。

网关封装还提供 Responses、Messages、Token 计数、Embeddings、Gemini 原生生成，以及图片和视频生成。模型和协议必须同时满足公开目录与当前用户权限，详见SDK 方法表和协议说明。SDK 不代替后端完成支付验收、权限校验或令牌刷新。