API 文档 | 星算AI

5 分钟入门

三步跑通你的第一个请求。

1. 获取 API 密钥
登录后进入控制台 → API 密钥，新建一把密钥，复制完整 xsai_sk_… 字符串。
2. 选择模型
在API 中转找到目标模型，复制它的 publicModelId（例如 gpt-5、claude-3.5-sonnet、gemini-1.5-pro）。
3. 发送请求
下面是用官方 OpenAI SDK 调用的最小示例：

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.xsai5.xyz/v1",
    api_key="xsai_sk_…",
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "你好，介绍一下你自己。"},
    ],
)
print(response.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.xsai5.xyz/v1",
  apiKey: "xsai_sk_…",
});

const response = await client.chat.completions.create({
  model: "gpt-5",
  messages: [
    { role: "user", content: "你好，介绍一下你自己。" },
  ],
});
console.log(response.choices[0].message.content);

curl https://api.xsai5.xyz/v1/chat/completions \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己。"}
    ]
  }'

鉴权

所有请求必须在 HTTP Header 里带上 Bearer Token：

Authorization: Bearer xsai_sk_xxxxxxxxxxxxxxxxxxxxxxxx

密钥以 xsai_sk_ 为前缀，仅在创建/重置那一刻可在控制台看到完整明文。
每把密钥可单独配置 额度上限、过期时间、允许的模型白名单，详见控制台「API 密钥」标签页。
密钥泄露请立即在控制台「重置」即可生成新密钥并自动失效旧密钥。

Base URL

统一入口：

https://api.xsai5.xyz/v1

所有端点路径都拼在这之后。例如对话补全完整地址为 https://api.xsai5.xyz/v1/chat/completions。

模型列表 · `GET /v1/models`

列出当前账户可调用的全部公开模型。响应格式与 OpenAI 完全一致。

models = client.models.list()
for m in models.data:
    print(m.id)

curl https://api.xsai5.xyz/v1/models \
  -H "Authorization: Bearer xsai_sk_…"

响应示例：

{
  "object": "list",
  "data": [
    { "id": "gpt-5",            "object": "model", "owned_by": "openai" },
    { "id": "claude-3.5-sonnet","object": "model", "owned_by": "anthropic" }
  ]
}

对话补全 · `POST /v1/chat/completions`

主力端点，覆盖文本对话、流式输出、工具调用、视觉理解、推理模型。

请求参数

model string · 必填 — 见模型列表返回的 id
messages array · 必填 — OpenAI 标准 messages 数组
stream boolean — true 时返回 SSE 流式响应，详见流式响应
tools array — function calling，详见工具调用
temperature / top_p / max_tokens 等所有 OpenAI 兼容参数原样转发

最小示例

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "你是个资深的 Python 工程师。"},
        {"role": "user",   "content": "用 Python 写一个快速排序。"},
    ],
    temperature=0.7,
    max_tokens=1000,
)
print(response.choices[0].message.content)

const response = await client.chat.completions.create({
  model: "gpt-5",
  messages: [
    { role: "system", content: "你是个资深的 Python 工程师。" },
    { role: "user",   content: "用 Python 写一个快速排序。" },
  ],
  temperature: 0.7,
  max_tokens: 1000,
});
console.log(response.choices[0].message.content);

curl https://api.xsai5.xyz/v1/chat/completions \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "system", "content": "你是个资深的 Python 工程师。"},
      {"role": "user",   "content": "用 Python 写一个快速排序。"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

响应示例

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 240,
    "total_tokens": 272
  }
}

图像生成 · `POST /v1/images/generations`

同步图像生成端点，参数与 OpenAI Images API 一致。

response = client.images.generate(
    model="gpt-image-1",
    prompt="A cat playing piano in space, watercolor style",
    size="1024x1024",
    n=1,
)
print(response.data[0].url)

curl https://api.xsai5.xyz/v1/images/generations \
  -H "Authorization: Bearer xsai_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "A cat playing piano in space, watercolor style",
    "size": "1024x1024",
    "n": 1
  }'

异步任务模式可通过 POST /v1/images/jobs 创建任务、GET /v1/images/jobs/{id} 轮询结果，适合长时间生成场景。

流式响应

在请求体里加 "stream": true，服务器将以 Server-Sent Events 形式逐个 token 推送增量。

stream = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "讲一个简短的故事"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "讲一个简短的故事" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

响应 Content-Type 为 text/event-stream，每条事件 data: {json}\n\n
结束事件为 data: [DONE]
计费仍按总 token 计算，与非流式一致

工具调用（Function Calling）

所有支持工具调用的模型（GPT-5 / Claude 3.5+ / Gemini 1.5+ 等）原生兼容 OpenAI tools 格式。

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",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto",
)
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

视觉理解

支持视觉的模型（带 vision 能力标记）可以在 messages.content 里放图片：

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

图片可以是 公开 URL 或 base64 data URI（data:image/jpeg;base64,…）。

错误码

所有错误响应遵循 OpenAI 错误格式：

{
  "error": {
    "message": "API 密钥已过期",
    "type": "authentication_error",
    "code": "key_expired"
  }
}

HTTP	code	说明
401	`authentication_error`	缺少 / 无效 / 已过期的 API 密钥
402	`insufficient_quota`	账户余额不足，或密钥额度已用尽
403	`permission_error`	密钥未授权调用此模型（白名单限制）
404	`model_not_found`	模型不存在
429	`rate_limit_exceeded`	触发并发限流
500	`api_error`	中转内部错误
502	`upstream_error`	上游返回错误
503	`model_channel_unavailable`	当前模型暂无可用上游通道
504	`timeout`	上游请求超时

计费与限流

计费

所有模型按 真实 token / 张数 实时扣费，单价见API 中转
缓存命中部分（prompt_tokens_details.cached_tokens）按对应模型的"缓存输入"价计费
失败请求 不扣费
每条请求扣费可在请求记录逐条核对

限流

用户级、密钥级、单模型通道级三段并发限制（详见控制台设置）
触发限流时返回 429 rate_limit_exceeded，建议指数退避重试

密钥级限制

每把密钥可在控制台单独配置：

额度上限：达到金额上限后该密钥停止扣费，账户其他密钥不受影响
过期时间：到期后自动失效
允许的模型白名单：仅勾选的模型可被该密钥调用，触发其他模型返回 403