使用文档

快速开始

几分钟内完成第一次调用：创建 API Key、配置 Base URL，然后发送一个 OpenAI 兼容的 Chat Completions 请求。

获取 API Key

先登录控制台，创建一个仅用于当前应用的密钥。

打开控制台，进入「API Keys」页面。
点击「新建密钥」，填写用途名称后保存。
复制生成的密钥，并保存到安全的位置。

密钥仅在创建时完整展示一次，离开页面后无法再次查看；如遗失请重新创建。

Base URL

https://<your-domain>/v1

将 <your-domain> 替换为你的部署域名，路径中的 /v1 不能省略。

发起第一个请求

所有请求都发往 POST /v1/chat/completions，请求体与 OpenAI Chat Completions 接口保持一致。下面的示例统一使用占位密钥 sk-... 与模型 gpt-4o。

curl https://<your-domain>/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己"}]
  }'

Python 与 Node.js 示例使用官方 OpenAI SDK，将 base_url 指向 /v1 即可；Go 与 Java 使用标准库，无需额外依赖。

实际可用的模型名以控制台「模型管理」中登记的对外模型名为准，示例中的 gpt-4o 仅作演示。

响应示例

调用成功后返回标准 Chat Completions 结构，usage 中给出本次请求的 Token 用量：

{
  "id": "chatcmpl-9x2kQ7f1",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是通过 Xin API 接入的模型，很高兴为你服务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

X-Request-Id

响应头中的 X-Request-Id 形如 xin_req_9f2c...，用于对账与排查。提交问题时附上该 ID，可以定位到完整的请求链路。

常见错误

接入初期最常见的问题集中在密钥、Base URL、限流与模型名四处：

401

密钥无效

Authorization 头缺少 Bearer 前缀、密钥已被删除或复制不完整。请到控制台重新创建密钥，并确认请求头格式为 Authorization: Bearer sk-...。

404

Base URL 少了 /v1

请求地址应为 https://<your-domain>/v1/chat/completions，注意保留路径中的 /v1。

429

RPM / TPM 超限

已达到密钥或模型的请求数 / Token 速率限制，降低并发、缩短上下文或稍后重试。

4xx

模型不存在

请求的模型名未在控制台登记为对外模型，请使用控制台「模型管理」中的对外模型名。