UnaAPI Docs
DEVELOPER GUIDE

快速开始

以下示例只使用 UnaAPI 公共接口、API Key 和公共模型别名。

1. 选择公共模型别名

打开模型广场，选择当前已启用的模型，并将示例中的 your-model-id 替换为对应公共别名。不要使用未出现在目录中的名称。

2. 保存 API Key

将 API Key 保存在服务端 Secret 或环境变量 UNA_API_KEY 中。不要写入前端代码、公开仓库、URL、日志或分析事件。

3. 发送请求

curl https://unaapi.com/v1/chat/completions \
  --connect-timeout 10 \
  --max-time 60 \
  -H "Authorization: Bearer una_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "用一句话介绍 UnaAPI"}],
    "stream": false
  }'

超时、重试与流式

  • 建议连接超时 10 秒、单次请求总超时 60 秒，并按业务场景调整。
  • 仅对网络错误、HTTP 429 和 5xx 做有限次数重试；使用指数退避并加入随机抖动。
  • 不要自动重试 400、401、403 等确定性客户端错误，先修正参数或凭据。
  • 需要流式输出时设置 stream: true，并确认所选模型在模型广场标注了流式能力；客户端应正确处理连接中断和未完成响应。

错误处理

HTTP 状态建议
400检查模型别名、消息结构和参数类型。
401 / 403检查 API Key 是否有效且具有调用权限。
429降低并发，并按退避策略稍后重试。
5xx记录请求时间与本地追踪信息，有限重试后降级处理。

安全注意

  • API Key 只应保存在受控服务端环境；浏览器和移动端应调用你自己的后端。
  • 不要在日志、错误页面、截图、URL 查询参数或客户端存储中记录完整 Key。
  • 按应用和环境拆分 Key，发现泄露后立即吊销并轮换。
  • 对外部输入设置长度、类型和内容边界，并为输出建立适合业务的安全检查。