通用

通用接口覆盖模型查询、对话、Responses、Claude Messages、文本嵌入、补全、音频、重排序、内容审核与实时连接。统一使用雪羊 AI API Key 鉴权。

获取模型列表

格式	方法	请求地址
OpenAI	GET	/v1/models
Gemini	GET	/v1beta/models

curl 'https://xueyangai.com/v1/models' \
  --header 'Authorization: Bearer sk-your-key'

OpenAI 格式（Chat）

兼容 OpenAI Chat Completions。现有 OpenAI SDK 只需替换接口基址和 API Key 即可接入。

基础信息

项目	内容
接口基址	https://xueyangai.com/v1
请求地址	POST /chat/completions
完整地址	https://xueyangai.com/v1/chat/completions
内容类型	application/json
鉴权方式	Authorization: Bearer <API Key>

请求示例

curl --location 'https://xueyangai.com/v1/chat/completions' \
  --header 'Authorization: Bearer sk-your-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍自己。"}
    ],
    "temperature": 0.7,
    "stream": false,
    "max_tokens": 1024
  }'

请求参数

参数	类型	必填	说明
model	string	是	模型 ID。
messages	object[]	是	按顺序排列的对话消息。
temperature	number	否	采样温度，值越高输出越随机。
top_p	number	否	核采样参数。
n	integer	否	生成数量。
stream	boolean	否	是否以 SSE 流式返回，默认关闭。
stream_options	object	否	流式响应选项。
stop	string	否	停止序列。
max_tokens	integer	否	最大生成 Token 数。
max_completion_tokens	integer	否	最大补全 Token 数。
presence_penalty	number	否	降低重复主题的倾向。
frequency_penalty	number	否	降低重复词语的倾向。
tools	object[]	否	工具调用定义。
tool_choice	string	否	none、auto 或 required。
response_format	object	否	指定输出格式。
seed	integer	否	尝试复现输出的随机种子。
reasoning_effort	string	否	推理强度：low、medium、high。

JavaScript 调用

const response = await fetch('https://xueyangai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.XUEYANGAI_API_KEY}`
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: '用三点总结这段文本。' }]
  })
})

const data = await response.json()
console.log(data.choices[0].message.content)

响应结构

成功响应的核心字段如下：

{
  "id": "id_xxx",
  "object": "chat.completion",
  "created": 1790250000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是一个 AI 助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 10,
    "total_tokens": 22
  }
}

状态码

状态码	含义	处理建议
200	请求成功	读取 choices[0].message.content。
400	请求参数错误	检查 model、messages 和 JSON 格式。
401	API Key 无效	重新复制密钥，确认 Bearer 前缀。
404	路径或模型不存在	检查完整接口地址和模型 ID。
429	额度不足或请求过于频繁	补充额度或稍后重试。

安全建议

• 在服务端或环境变量中保存 API Key，不要放在浏览器前端。
• 给不同应用使用不同密钥，便于定位和撤销。
• 生产环境记录请求 ID 和状态码，不要记录完整的 Authorization 请求头。

OpenAI 格式（Responses）

方法	请求地址	说明
POST	/v1/responses	创建 OpenAI Responses API 响应。
POST	/v1/responses/compact	压缩较长的对话上下文。

curl 'https://xueyangai.com/v1/responses' \
  --header 'Authorization: Bearer sk-your-key' \
  --header 'Content-Type: application/json' \
  --data '{"model":"gpt-4o","input":"你好"}'

Claude 格式（Messages）

使用 Anthropic Claude Messages 请求格式创建对话。

POST /v1/messages

请求头需要包含 Authorization: Bearer <API Key> 和 Content-Type: application/json。

Gemini 格式

方法	请求地址	说明
POST	/v1/engines/{model}/embeddings	Gemini 格式嵌入接口。

Gemini 图片生成接口位于图片接口。

OpenAI 格式（Embeddings）

POST /v1/embeddings

将文本或文本数组转换为向量。请求体至少包含 model 和 input。

{
  "model": "text-embedding-3-small",
  "input": ["第一段文本", "第二段文本"]
}

文本补全（Completions）

POST /v1/completions

兼容旧版 OpenAI Completions 格式。新项目优先使用 Chat Completions 或 Responses API。

OpenAI 音频（Audio）

方法	请求地址	说明
POST	/v1/audio/transcriptions	将音频转写为文本。
POST	/v1/audio/translations	将音频翻译为文本。
POST	/v1/audio/speech	将文本转换为语音。

上传音频时使用 multipart/form-data；语音合成使用 application/json。

重排序（Rerank）

POST /v1/rerank

对候选文档进行相关性重排序。请求体包含查询文本、候选文档和模型 ID。

内容审核（Moderations）

POST /v1/moderations

检测输入内容中的潜在风险类别。请求体包含 model 和 input。

实时接口（Realtime）

GET /v1/realtime

建立实时 WebSocket 连接。客户端需要在握手阶段携带有效的 API Key。