Chat Completions & Messages API

SuperRoute 提供两个协议的兼容接口：

• OpenAI Chat Completions → GPT 系列、Gemini 系列
• Anthropic Messages → Claude 系列

一篇文档看全两个端点的差异。已用 OpenAI/Anthropic SDK 的代码只需改 base_url。

协议对照（一眼看差异）

共同部分

鉴权（共通原理）

每个 API Key 在创建时绑定档位和协议：

• ⚡ fast / 🛡️ stable / 🚀 full：用哪档都行（同一 Key 可调所有模型）
• 协议匹配：按照 SuperRoute 控制台为该 API Key 分配的协议调用对应端点

不同协议的鉴权 Header：

流式响应（共同）

加 "stream": true 即可。两个协议都返回 SSE（Server-Sent Events）。

stream = client.chat.completions.create(
    model="gpt-5-6-luna",  # 或 claude-sonnet-5
    stream=True,
    messages=[{"role": "user", "content": "讲个笑话"}],
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if hasattr(chunk.choices[0].delta, 'content') else chunk.choices[0].delta.text
    if delta:
        print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "gpt-5-6-luna",  // 或 claude-sonnet-5
  stream: true,
  messages: [{ role: "user", content: "讲个笑话" }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

错误响应（统一格式）

所有错误统一返回 OpenAI 风格 JSON（即使调用的是 Anthropic 协议）：

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

完整错误排查见 报错与踩坑。

OpenAI Chat Completions

端点

POST https://api.superoute.uk/v1/chat/completions

鉴权

Authorization: Bearer <控制台生成的 API Key>

支持的模型

gpt-5-6-luna、gpt-5-6-sol、gpt-5-6-terra、gpt-5-5、gpt-5-4、gpt-5-4-mini 全系可用。也支持 Gemini 系列（用同协议调）。

请求示例（多语言）

curl https://api.superoute.uk/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-luna",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

from openai import OpenAI
client = OpenAI()  # 自动读 OPENAI_BASE_URL 和 OPENAI_API_KEY

response = client.chat.completions.create(
    model="gpt-5-6-luna",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";
const client = new OpenAI();
const completion = await client.chat.completions.create({
  model: "gpt-5-6-luna",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(completion.choices[0].message.content);

package main

import (
    "context"
    "fmt"
    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
    "os"
)

func main() {
    client := openai.NewClient(
        option.WithBaseURL(os.Getenv("OPENAI_BASE_URL")),
        option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
    )
    resp, _ := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: openai.ChatModel("gpt-5-6-luna"),
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("用一句话介绍你自己"),
        },
    })
    fmt.Println(resp.Choices[0].Message.Content)
}

Function Calling（工具调用）

import json
from openai import OpenAI

client = OpenAI()

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-5-6-luna",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"调用工具: {tool_call.function.name}, 参数: {args}")

结构化输出（JSON 模式）

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class TodoItem(BaseModel):
    title: str
    priority: int

response = client.chat.completions.create(
    model="gpt-5-6-luna",
    messages=[
        {"role": "system", "content": "从用户输入中提取待办事项"},
        {"role": "user", "content": "明天下午 3 点前完成代码 review"},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "todo",
            "schema": TodoItem.model_json_schema()
        }
    }
)
print(response.choices[0].message.content)

多模态（图像理解）

response = client.chat.completions.create(
    model="gpt-5-6-luna",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么？"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
        ]
    }]
)

推理模型（GPT-5.6 Sol）

response = client.chat.completions.create(
    model="gpt-5-6-sol",
    messages=[{"role": "user", "content": "9.11 和 9.9 哪个更大？"}],
    reasoning_effort="high",  # low / medium / high
    max_completion_tokens=10000
)

错误码速查

完整排查见 报错与踩坑。

Anthropic Messages

端点

POST https://api.superoute.uk/v1/messages

鉴权

x-api-key: <控制台生成的 API Key>
anthropic-version: 2023-06-01

支持的模型

claude-opus-4-8、claude-sonnet-5、claude-fable-5、claude-haiku-4-5 等 Claude 全系 可用。

请求示例（多语言）

curl https://api.superoute.uk/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

import anthropic
client = anthropic.Anthropic()  # 自动读 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(message.content[0].text);

package main

import (
    "context"
    "fmt"
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
    "os"
)

func main() {
    client := anthropic.NewClient(
        option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")),
        option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    )
    msg, _ := client.Messages.New(context.Background(), anthropic.MessageNewParams{
        Model:     anthropic.ModelClaudeSonnet5,
        MaxTokens: 1024,
        Messages: []anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock("用一句话介绍你自己")),
        },
    })
    fmt.Println(msg.Content[0].Text)
}

Tool Use（工具调用）

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "get_weather",
    "description": "获取指定城市的天气",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名"}
        },
        "required": ["city"]
    }
}]

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}]
)

for block in response.content:
    if block.type == "tool_use":
        print(f"调用工具: {block.name}, 参数: {block.input}")

Extended Thinking（扩展思考）

让 Claude 先"内心独白"推理，再给出最终答案。适合复杂推理、代码、Agent 决策。

启用思考

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "9.11 和 9.9 哪个更大？请详细推理。"}]
)

for block in response.content:
    if block.type == "thinking":
        print("=== 思考 ===\n", block.thinking)
    elif block.type == "text":
        print("=== 回答 ===\n", block.text)

参数详解

注意事项

长 system prompt + 重复调用场景下自动降低输入 token 成本。控制台可查看缓存命中明细。

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "你是一个资深 Python 工程师...",
        "cache_control": {"type": "ephemeral"}  # 标记为可缓存
    }],
    messages=[{"role": "user", "content": "如何优化这段代码？"}]
)
print("缓存命中:", response.usage.cache_read_input_tokens, "tokens")

多模态（图像理解）

# 方式 1：URL
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}},
            {"type": "text", "text": "这张图里有什么？"}
        ]
    }]
)

# 方式 2：base64
import base64
img_data = base64.b64encode(open("local.png", "rb").read()).decode()
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [{
            "type": "image",
            "source": {
                "type": "base64",
                "media_type": "image/png",
                "data": img_data
            }
        }, {"type": "text", "text": "这张图里有什么？"}]
    }]
)

System Prompt

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="你是一个资深的 Python 工程师，擅长代码审查。",  # 顶层 system 字段
    messages=[{"role": "user", "content": "请审查这段代码：..."}]
)

错误码速查

完整排查见 报错与踩坑。

跨协议能力对照

SuperRoute 平台特有行为

详见各自章节（OpenAI / Anthropic 上方）末尾的 "SuperRoute 特有行为"。

完整错误排查见 报错与踩坑。