UnaAPI Docs
DEVELOPER GUIDE

移动端接入

移动应用调用自己的业务后端，由后端安全持有 UnaAPI Key 并转发模型请求。

不要把 UnaAPI Key 放进 App

APK、AAB、IPA、前端资源和远程配置都可能被提取。推荐链路是：移动 App → 你的业务后端 → UnaAPI。

推荐架构

  1. App 使用你自己的登录态调用业务后端，不直接携带 UnaAPI Key。
  2. 业务后端校验用户、权限、配额和输入边界，再从 Secret 管理系统读取 UnaAPI Key。
  3. 业务后端调用 UnaAPI，并只把业务需要的响应字段返回 App。
  4. 服务端日志只记录脱敏请求标识、状态和耗时，不记录完整 Key 或敏感提示词。

iOS 与 Android 示例

以下代码调用你自己的后端。示例中的后端负责附加 UnaAPI Authorization Header。

Swift / URLSession
struct ChatRequest: Encodable {
    let model: String
    let prompt: String
}

var request = URLRequest(url: URL(string: "https://your-backend.example.com/ai/chat")!)
request.httpMethod = "POST"
request.timeoutInterval = 60
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(ChatRequest(
    model: "your-model-id",
    prompt: "你好"
))

let (data, response) = try await URLSession.shared.data(for: request)
Kotlin / OkHttp
val body = """{
  "model": "your-model-id",
  "prompt": "你好"
}""".toRequestBody("application/json".toMediaType())

val request = Request.Builder()
  .url("https://your-backend.example.com/ai/chat")
  .post(body)
  .build()

val response = okHttpClient.newCall(request).execute()

网络与生命周期

  • 设置连接超时与总超时；页面退出、任务取消或 App 进入不适合继续联网的状态时取消请求。
  • 网络切换、断网、429 和 5xx 只能有限重试，并使用指数退避与随机抖动。
  • 对可能产生重复副作用的业务操作不要自动重试；模型请求是否重试应由你的业务后端明确控制。
  • 流式输出应增量解析，并处理半包、断流、后台切换和用户主动停止。

安全与隐私注意事项

  • 不要把完整 Key 写入源码、构建参数、剪贴板、URL、埋点、崩溃日志或截图。
  • 移动端只保存自己的短期会话凭据；使用系统安全存储，并支持远程失效和轮换。
  • 只收集完成业务所需的提示词和模型输出；敏感内容上传前应取得用户授权并提供删除机制。
  • 强制 HTTPS。若采用证书固定，必须设计证书轮换和紧急回退，避免证书更新导致全量断网。
  • 服务端按用户和设备实施限流、并发保护、内容长度限制和异常行为审计。

错误处理建议

状态移动端处理
400提示用户修正输入，不自动重试。
401 / 403刷新你自己的登录态；不要把 UnaAPI Key 下发到客户端。
402提示账户余额不足，并引导到受控充值流程。
429读取 Retry-After，降低频率后再试。
502 / 503 / 504显示可恢复错误；有限重试后允许用户手动重试。

上线前检查

  • 反编译安装包确认没有 UnaAPI Key、内部地址或调试 Secret。
  • 验证弱网、断网、切网、后台恢复、取消请求和超时体验。
  • 验证服务端限流、余额不足、上游故障和 Key 吊销后的固定错误语义。
  • 确认隐私政策覆盖模型输入输出的收集、传输、留存和删除规则。