快速开始

本页通过 OpenAI 兼容接口完成一次对话请求。开始前需要在 TopAPIs 控制台 创建 API Key，并确认账号可以访问至少一个对话模型。

接入地址

https://api.topapis.cn/v1

所有请求均使用 HTTPS。JSON 接口应发送 Content-Type: application/json。

1. 保存 API Key

将密钥保存在服务端环境变量中，不要写入源代码。

Linux / macOS

export TOPAPIS_API_KEY="YOUR_API_KEY"

PowerShell

$env:TOPAPIS_API_KEY = "YOUR_API_KEY"

2. 查询可用模型

账号、分组和通道权限会影响模型列表。调用接口获取当前账号的实时结果：

curl "https://api.topapis.cn/v1/models" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY"

响应中的 data[].id 是后续请求可使用的模型标识。不要依赖从其他账号复制的静态清单。

3. 发起对话请求

将 YOUR_MODEL 替换为上一步返回的模型标识。

curl "https://api.topapis.cn/v1/chat/completions" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      { "role": "user", "content": "用一句话介绍 TopAPIs。" }
    ]
  }'

典型的非流式响应包含 choices[0].message.content：

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TopAPIs 提供统一的模型 API 接入服务。"
      },
      "finish_reason": "stop"
    }
  ]
}

4. 检查失败响应

• 401：检查密钥是否正确，以及请求头是否以 Bearer 开头。
• 403：当前账号、分组或令牌没有访问该模型的权限。
• 429：请求频率或额度达到限制，应降低并发并延迟重试。
• 5xx：服务或上游临时异常，可进行有限次数的退避重试。

完整处理策略见错误码与重试。

下一步

• 阅读 API 鉴权 配置密钥存储与轮换。
• 阅读 模型列表 了解如何选择账号可用模型。