API Reference

UniKey 中转站基于开源框架 NewAPI 搭建。对于应用开发者，UniKey 暴露的是完全兼容 OpenAI 格式的 AI Model APIs。

本页只说明调用方需要使用的模型接口。NewAPI 还提供用于后台管理的 Management APIs，例如渠道、模型、Token、支付和日志管理；普通 UniKey API 调用不需要使用这些管理接口。

第一个 API 请求

200 OK

POST/v1/chat/completions

REQUEST

curl -X POST "/v1/chat/completions" \
  -H "Authorization: Bearer $UNIKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unikey-router",
    "messages": [{ "role": "user", "content": "Hello Unikey" }]
  }'

RESPONSE

{
  "choices": [{ "message": { "content": "Chat request routed." } }],
  "usage": { "total_tokens": 27 }
}

Base URL

https://www.getunikey.ai

认证

使用 UniKey 控制台创建的 API Key：

Authorization: Bearer $UNIKEY_API_KEY

大多数 OpenAI 兼容 SDK 都使用 Authorization: Bearer 请求头。不要把 API Key 放进前端代码、浏览器包、移动端安装包或公开仓库。

OpenAI SDK 示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.UNIKEY_API_KEY,
  baseURL: 'https://www.getunikey.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-5.2',
  messages: [{role: 'user', content: 'Hello from UniKey'}],
});

console.log(response.choices[0]?.message?.content);

列出模型

GET /v1/models
Authorization: Bearer $UNIKEY_API_KEY

示例响应：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.2",
      "object": "model",
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "claude-sonnet-4-6",
      "object": "model",
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    }
  ]
}

NewAPI 底层可以根据请求头为 OpenAI、Anthropic 或 Gemini 风格客户端适配模型列表。普通 OpenAI 兼容调用只需要发送 Authorization: Bearer。

Chat Completions

POST /v1/chat/completions
Authorization: Bearer $UNIKEY_API_KEY
Content-Type: application/json

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello UniKey"
    }
  ],
  "stream": false,
  "max_tokens": 1024,
  "temperature": 1
}

该接口兼容 OpenAI Chat Completions，常用字段包括：

字段	类型	说明
`model`	string	`/v1/models` 返回或 UniKey 文档列出的模型 ID。
`messages`	array	包含 `system`、`user`、`assistant` 或 `tool` 角色的消息列表。
`stream`	boolean	`false` 返回 JSON，`true` 返回 SSE 流式响应。
`temperature`	number	采样温度，通常在 `0` 到 `2` 之间。
`top_p`	number	核采样参数，通常在 `0` 到 `1` 之间。
`max_tokens`	number	最大生成 Token 数。
`presence_penalty`	number	OpenAI 兼容 presence penalty。
`frequency_penalty`	number	OpenAI 兼容 frequency penalty。
`tools`	array	兼容模型的工具或函数定义。
`tool_choice`	string/object	工具选择策略。

非流式响应

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

流式响应

将 stream 设置为 true 后，接口会返回 Server-Sent Events。每个 chunk 使用 OpenAI 兼容流式结构：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}

data: [DONE]

Completions

传统文本补全接口：

POST /v1/completions
Authorization: Bearer $UNIKEY_API_KEY
Content-Type: application/json

{
  "model": "gpt-5.2",
  "prompt": "Write a one-sentence product description for UniKey."
}

新集成建议优先使用 Chat Completions。只有旧版 OpenAI 兼容客户端明确依赖 /v1/completions 时，再使用该接口。

Embeddings

POST /v1/embeddings
Authorization: Bearer $UNIKEY_API_KEY
Content-Type: application/json

{
  "model": "text-embedding-ada-002",
  "input": "UniKey is a unified AI capability gateway."
}

Anthropic 兼容 Messages

/v1/messages 用于 Anthropic 兼容客户端，包括 Claude Code。

POST /v1/messages
x-api-key: $UNIKEY_API_KEY
Content-Type: application/json

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {
      "role": "user",
      "content": "Hello, Claude-compatible UniKey."
    }
  ],
  "stream": false
}

如果客户端只支持 OpenAI SDK，请使用 /v1/chat/completions。

错误响应

{
  "error": {
    "message": "Error message",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

端点汇总

端点	兼容格式	用途
`GET /v1/models`	OpenAI 兼容模型列表	列出可用模型。
`POST /v1/chat/completions`	OpenAI Chat Completions	主要聊天与 Agent 请求接口。
`POST /v1/completions`	OpenAI legacy completions	旧版 Prompt 补全客户端。
`POST /v1/embeddings`	OpenAI embeddings	文本向量生成。
`POST /v1/messages`	Anthropic 兼容	Claude Code 等 Claude 风格客户端。

第一个 API 请求​

Base URL​

认证​

OpenAI SDK 示例​

列出模型​

Chat Completions​

非流式响应​

流式响应​

Completions​

Embeddings​

Anthropic 兼容 Messages​

错误响应​

端点汇总​