星绒 API开发者文档
控制台
文档›开始›快速入门

快速入门

星绒 API 提供 OpenAI 兼容的统一接口。只需一个 Base URL、一个 API Key 和一个可用模型名称，即可接入当前已开放的文本对话模型。

服务已上线OpenAI CompatibleHTTPS按实际 Token 计费

接入三要素

项目星绒 API 配置
Base URLhttps://api.xrstudio.cn/v1
API Key在控制台的令牌页面创建，以 Authorization: Bearer sk-... 发送
模型从控制台模型列表选择，或通过 GET /v1/models 获取当前 Key 可用模型
先确认模型权限模型与线路会动态调整。不要根据第三方模型列表硬编码，始终以你的 API Key 调用 /v1/models 返回的结果为准。

完成首次调用

  1. 登录并创建 API Key进入星绒 API 控制台，在令牌页面创建 Key。Key 只显示和使用于受信任的服务端环境。
  2. 获取可用模型调用模型列表接口，选择返回结果中的模型 ID。
  3. 发送对话请求将模型 ID 填入 model，向对话补全接口发送消息。
bash
curl https://api.xrstudio.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ],
    "stream": false
  }'

SDK 接入

Python

python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.xrstudio.cn/v1",
)

response = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Node.js

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XR_API_KEY,
  baseURL: "https://api.xrstudio.cn/v1",
});

const response = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{ role: "user", content: "你好" }],
});
console.log(response.choices[0].message.content);

模型列表

GET/v1/models

返回当前 API Key 有权调用的模型。模型名称必须使用响应中的 id 原样传递。

bash
curl https://api.xrstudio.cn/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

对话补全

POST/v1/chat/completions
参数说明
model必填。使用 /v1/models 返回的模型 ID。
messages必填。对话消息数组，常用角色为 system、user、assistant。
stream可选。设为 true 时使用 SSE 流式响应。
temperature可选。仅在目标模型支持时生效。
max_tokens可选。最大输出 Token，最终上限由模型和上游决定。

流式响应

设置 stream: true 后，服务通过 Server-Sent Events 返回增量内容。客户端持续读取 data: 行，并在收到 [DONE] 后结束。

python
stream = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "写一段简短介绍"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

API Key

  • API Key 属于敏感凭据，不要写入浏览器前端、公开仓库、截图或日志。
  • 建议通过服务端环境变量读取，例如 XR_API_KEY。
  • 按应用或环境分别创建 Key，便于限制模型、线路和额度。
  • 怀疑泄漏时立即停用旧 Key，并创建新 Key。

额度与计费

星绒 API 根据实际输入、输出 Token、模型倍率及线路倍率扣费。未发起调用不会扣除额度。

规则说明
额度换算1 额度 = 500,000 quota
充值价格当前基础价格由控制台实时显示；现行配置下 1 额度支付 ¥0.8
调用扣费以实际 Token、模型输入/输出倍率、线路倍率及缓存规则综合计算
余额未使用额度保留在账户中，可在控制台查看用量日志
价格以控制台实时配置为准不同模型与线路成本不同。请求前请在模型列表和控制台确认当前可用性及倍率。

模型与线路

同一模型可能由多条线路提供，不同线路可能有不同倍率、延迟和可用性。API Key 会受到创建时所选模型和线路分组限制；出现 403 或模型不可用时，请检查 Key 的模型权限与分组。

错误排查

现象常见原因处理方式
401Key 无效、停用或请求头缺失检查 Bearer Token，不要附加多余引号或空格。
403Key 无模型或线路权限检查模型限制与线路分组。
404Base URL、路径或模型名错误确认使用 /v1 和模型列表返回的 ID。
429频率限制、并发限制或额度不足检查余额并采用指数退避。
500/502/503服务或上游暂时异常保存请求 ID、模型和时间，稍后有限次数重试。
返回 HTML请求到了网页地址而非 API检查 Base URL 是否为 https://api.xrstudio.cn/v1。

安全建议

  • 仅通过 HTTPS 调用，不要关闭 TLS 证书校验。
  • 在服务端设置合理的连接、读取和总请求超时。
  • 仅对 429、502、503 等可恢复错误进行有限次数指数退避，不要无限重试。
  • 记录请求 ID、状态码、模型和耗时，但不要记录完整 API Key 或隐私数据。
  • AI 输出可能存在错误，不应作为医疗、法律、金融等高风险决策的唯一依据。
‹ 返回星绒 API 控制台下一步 ›完成首次调用

© 2026 星绒 API · 文档内容以线上接口和控制台实时配置为准。