API 参考

玄州API 兼容 OpenAI API 格式，所有接口均通过 HTTPS 访问。

基础信息

项目	值
接口地址	https://xuanzhouapi.top
认证方式	HTTP Bearer Token（API Key）
请求格式	JSON
响应格式	JSON（或 SSE 流）
编码	UTF-8

认证

所有 API 请求需要在 HTTP Header 中携带 API Key：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

API Key 在控制台「密钥管理」页面创建。

API 端点

对话补全

POST /v1/chat/completions

发送对话消息并获取模型回复。

请求参数

参数	类型	必填	说明
model	string	是	模型名称
messages	array	是	对话消息列表
max_tokens	integer	否	最大输出 token 数，默认 4096
temperature	number	否	采样温度 0-2，默认 1
top_p	number	否	核采样 0-1，默认 1
stream	boolean	否	是否流式输出，默认 false
frequency_penalty	number	否	频率惩罚 -2.0 到 2.0
presence_penalty	number	否	存在惩罚 -2.0 到 2.0
stop	string/array	否	停止词

Message 格式

{
  "role": "user | system | assistant",
  "content": "消息内容文本"
}

多模态（图片理解）：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
  ]
}

请求示例

curl https://xuanzhouapi.top/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手"},
      {"role": "user", "content": "你好，介绍一下你自己"}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

成功响应

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是 GPT-5.5..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 30,
    "total_tokens": 50
  }
}

finish_reason 说明

值	说明
stop	正常完成或命中停止词
length	达到 max_tokens 上限
content_filter	内容被安全过滤

流式响应

当 stream: true 时，响应格式为 SSE（Server-Sent Events）：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.5","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"！"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

错误响应

{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误码"
  }
}

常见错误码：

HTTP 状态码	说明
401	API Key 无效或缺失
429	请求频率超限
500	服务器内部错误

图片生成

POST /v1/images/generations

使用 gpt-image-2 模型生成图片。

请求参数

参数	类型	必填	说明
model	string	是	固定为 gpt-image-2
prompt	string	是	图片描述文本
n	integer	否	生成数量 1-10，默认 1
size	string	否	尺寸，默认 1024x1024
response_format	string	否	url 或 b64_json，默认 url

支持尺寸：

• 1024x1024（正方形）
• 1792x1024（横版）
• 1024x1792（竖版）

请求示例

curl https://xuanzhouapi.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只可爱的橙色猫咪坐在花园里，阳光温暖",
    "n": 1,
    "size": "1024x1024"
  }'

响应

{
  "created": 1712345678,
  "data": [
    {
      "url": "https://cdn.example.com/generated-image.png",
      "revised_prompt": "一只橘色的可爱猫咪..."
    }
  ]
}

模型列表

GET /v1/models

获取所有可用模型。

请求示例

curl https://xuanzhouapi.top/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"

响应

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

Claude 原生接口

部分 Claude 模型支持 Anthropic 原生的 /v1/messages 接口：

POST /v1/messages

用法与 Anthropic 官方 API 一致，将 base_url 从 https://api.anthropic.com 替换为 https://xuanzhouapi.top 即可。

curl https://xuanzhouapi.top/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

注意：Claude 原生接口使用 x-api-key Header 而非 Authorization: Bearer。