OpenAI 格式

SuperToken 提供完全兼容 OpenAI 的 API 接口，支持 GPT 系列模型以及其他兼容 OpenAI 格式的模型。

接口地址

text

https://api.supertoken.cc/v1

认证方式

在请求头中添加 API 密钥：

http

Authorization: Bearer YOUR_API_KEY

Chat Completions

接口说明

用于文本对话的核心接口，支持单轮和多轮对话。

请求地址

text

POST /v1/chat/completions

重要说明

GPT 模型流式输出要求：

所有 GPT 系列模型必须使用流式输出，建议直接用于 Codex 等工具
请求中必须设置 "stream": true
非流式请求会返回错误

其他模型（Claude、Gemini 等）支持流式和非流式两种模式。

请求示例

GPT 模型（必须流式）

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {
        "role": "system",
        "content": "你是一个有帮助的AI助手"
      },
      {
        "role": "user",
        "content": "用Python写一个快速排序"
      }
    ],
    "stream": true,
    "temperature": 0.7,
    "max_tokens": 2000
  }'

其他模型（可选流式）

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": false,
    "temperature": 0.7
  }'

请求参数

参数	类型	必填	说明
model	string	是	模型名称，如 `gpt-5.2`
messages	array	是	对话消息列表
stream	boolean	GPT 模型必填	GPT 模型必须设为 `true`，其他模型可选
temperature	number	否	温度参数，0-2，默认 1
max_tokens	integer	否	最大生成 token 数
top_p	number	否	核采样参数，0-1
stop	string/array	否	停止序列
stream_options	object	否	流式输出选项

Messages 格式

json

{
  "messages": [
    {
      "role": "system",
      "content": "系统提示词"
    },
    {
      "role": "user",
      "content": "用户消息"
    },
    {
      "role": "assistant",
      "content": "助手回复"
    }
  ]
}

角色说明：

system：系统提示词，设定 AI 行为
user：用户消息
assistant：AI 的回复，用于多轮对话

响应格式

json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是AI的回复内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 56,
    "completion_tokens": 31,
    "total_tokens": 87
  }
}

流式输出

GPT 模型必须使用流式输出，其他模型可选。

GPT 模型流式请求

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

流式响应格式（SSE）

text

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.2","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.2","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.2","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-5.2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":2,"total_tokens":11}}

data: [DONE]

非 GPT 模型（可选流式）

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

支持的模型

GPT 系列（必须流式输出）

模型	说明	上下文	流式要求
gpt-5.2	最新 GPT-5 模型	200K	必须
gpt-5.2-codex	代码优化版	200K	必须
gpt-5.1	稳定版本	128K	必须
gpt-5-codex-mini	轻量版	128K	必须

Claude 系列（OpenAI 格式，可选流式）

模型	说明	上下文	流式要求
claude-opus-4-6	最强 Claude	200K	可选
claude-sonnet-4-6	平衡版	200K	可选
claude-haiku-4-5	快速版	200K	可选

Gemini 系列（OpenAI 格式，可选流式）

模型	说明	上下文	流式要求
gemini-2.5-pro	Gemini 旗舰	1M	可选
gemini-2.0-flash	快速版	1M	可选

代码示例

Python（GPT 模型流式）

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.supertoken.cc/v1"
)

stream = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "system", "content": "你是一个编程助手"},
        {"role": "user", "content": "写一个Python函数计算斐波那契数列"}
    ],
    stream=True,
    stream_options={"include_usage": True}
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

    if hasattr(chunk, "usage") and chunk.usage:
        print(f"\n\n使用了 {chunk.usage.total_tokens} tokens")

Python（非 GPT 模型，可选流式）

python

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "写一个快速排序算法"}
    ],
    stream=False
)

print(response.choices[0].message.content)

Node.js（GPT 模型流式）

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.supertoken.cc/v1"
});

async function main() {
  const stream = await client.chat.completions.create({
    model: "gpt-5.2",
    messages: [
      { role: "system", content: "你是一个编程助手" },
      { role: "user", content: "写一个快速排序算法" }
    ],
    stream: true,
    stream_options: { include_usage: true }
  });

  for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }

    if (chunk.usage) {
      console.log(`\n\n使用了 ${chunk.usage.total_tokens} tokens`);
    }
  }
}

main();

Node.js（非 GPT 模型）

javascript

async function callClaude() {
  const completion = await client.chat.completions.create({
    model: "claude-sonnet-4-6",
    messages: [
      { role: "user", content: "写一个快速排序算法" }
    ],
    stream: false
  });

  console.log(completion.choices[0].message.content);
}

cURL（GPT 模型）

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

cURL（非 GPT 模型）

bash

curl https://api.supertoken.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false
  }'

错误处理

错误响应格式

json

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

常见错误码

状态码	错误类型	说明
401	invalid_api_key	API 密钥无效
429	rate_limit_exceeded	请求频率超限
500	server_error	服务器错误
503	service_unavailable	服务不可用

错误处理示例

python

from openai import OpenAI, APIError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.supertoken.cc/v1"
)

try:
    stream = client.chat.completions.create(
        model="gpt-5.2",
        messages=[{"role": "user", "content": "Hello"}],
        stream=True
    )

    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")

except APIError as e:
    print(f"API错误: {e.message}")
    print(f"错误类型: {e.type}")
    print(f"状态码: {e.status_code}")

最佳实践

1. 使用流式输出（GPT 模型必须）

GPT 模型必须使用流式输出，其他模型可选：

python

stream = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "写一篇文章"}],
    stream=True,
    stream_options={"include_usage": True}
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

2. 控制 Token 消耗

python

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[...],
    max_tokens=500,
    temperature=0.3
)

3. 设置合理超时和重试

建议为请求设置超时，并实现指数退避重试。

速率限制

SuperToken 实施以下速率限制：

限制类型	限制值
每分钟请求数	60
每小时请求数	3600
并发请求数	10

超过限制会返回 429 错误，建议实现指数退避重试。

OpenAI 格式 ​

接口地址 ​

认证方式 ​

Chat Completions ​

接口说明 ​

请求地址 ​

重要说明 ​

请求示例 ​

GPT 模型（必须流式） ​

其他模型（可选流式） ​

请求参数 ​

Messages 格式 ​

响应格式 ​

流式输出 ​

GPT 模型流式请求 ​

流式响应格式（SSE） ​

非 GPT 模型（可选流式） ​

支持的模型 ​

GPT 系列（必须流式输出） ​

Claude 系列（OpenAI 格式，可选流式） ​

Gemini 系列（OpenAI 格式，可选流式） ​

代码示例 ​

Python（GPT 模型流式） ​

Python（非 GPT 模型，可选流式） ​

Node.js（GPT 模型流式） ​

Node.js（非 GPT 模型） ​

cURL（GPT 模型） ​

cURL（非 GPT 模型） ​

错误处理 ​

错误响应格式 ​

常见错误码 ​

错误处理示例 ​

最佳实践 ​

1. 使用流式输出（GPT 模型必须） ​

2. 控制 Token 消耗 ​

3. 设置合理超时和重试 ​

速率限制 ​

下一步 ​

OpenAI 格式

接口地址

认证方式

Chat Completions

接口说明

请求地址

重要说明

请求示例

GPT 模型（必须流式）

其他模型（可选流式）

请求参数

Messages 格式

响应格式

流式输出

GPT 模型流式请求

流式响应格式（SSE）

非 GPT 模型（可选流式）

支持的模型

GPT 系列（必须流式输出）

Claude 系列（OpenAI 格式，可选流式）

Gemini 系列（OpenAI 格式，可选流式）

代码示例

Python（GPT 模型流式）

Python（非 GPT 模型，可选流式）

Node.js（GPT 模型流式）

Node.js（非 GPT 模型）

cURL（GPT 模型）

cURL（非 GPT 模型）

错误处理

错误响应格式

常见错误码

错误处理示例

最佳实践

1. 使用流式输出（GPT 模型必须）

2. 控制 Token 消耗

3. 设置合理超时和重试

速率限制

下一步