# 产品使用说明

# 目录

• 快速开始
  • 1.1 API接入
  • 1.2 错误码速查
  • 1.3 速率限制

# 1.1 API接入

欢迎使用星辰 MaaS 平台模型服务。为便于您快速调用，以下为您提供接口调用地址与参考示例。

接口地址

• POST Chat https://maas-api.cn-huabei-1.xf-yun.com/v2/chat/completions (opens new window)
• POST Responses https://maas-api.cn-huabei-1.xf-yun.com/v1/responses (opens new window)
• POST Anthropic https://maas-api.cn-huabei-1.xf-yun.com/anthropic/v1/messages (opens new window)

认证信息

• API Key： 点击 API调用 (opens new window) / API管理 (opens new window) 界面获取，示例：ak-f30b1********fc84b82e86a
• Model ID： 点击 API调用 (opens new window) 获取，示例：spark-x2.5

下面以 Chat Completions 为例完成一次最小调用，便于快速验证接入是否成功；如需流式输出，将 stream 设置为 true。

CURL

curl https://maas-api.cn-huabei-1.xf-yun.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SPARK_API_PASSWORD" \
  -d '{
    "model": "spark-x2.5",
    "messages": [
      {"role": "user", "content": "你好。"}
    ],
    "stream": false
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="<你的 APIPassword>",
    base_url="https://maas-api.cn-huabei-1.xf-yun.com/v2",
)

response = client.chat.completions.create(
    model="spark-x2.5",
    messages=[{"role": "user", "content": "你好。"}],
    stream=False,
)

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

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body := map[string]any{
        "model": "spark-x2.5",
        "messages": []map[string]string{
            {"role": "user", "content": "你好。"},
        },
        "stream": false,
    }

    data, err := json.Marshal(body)
    if err != nil {
        panic(err)
    }

    req, err := http.NewRequest(
        http.MethodPost,
        "https://maas-api.cn-huabei-1.xf-yun.com/v2/chat/completions",
        bytes.NewReader(data),
    )
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer <你的 APIPassword>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    result, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(result))
}

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SPARK_API_PASSWORD,
  baseURL: "https://maas-api.cn-huabei-1.xf-yun.com/v2",
});

const response = await client.chat.completions.create({
  model: "spark-x2.5",
  messages: [{ role: "user", content: "你好。" }],
  stream: false,
});

console.log(response.choices[0].message.content)

# 1.2 错误码速查

接口调用失败时，可结合 HTTP Code、Error Code、原因和解决办法定位问题。

# 1.3 速率限制

# 1 限制维度

为保障平台稳定性和公平性，星辰 MaaS 对 API 调用实行速率限制。本文说明限制规则、错误码、响应头以及触发限流后的处理建议。

星辰 MaaS 采用 双重限流 机制，按维度独立计算、互不抵扣：

两个维度任一触顶即触发限流。流式输出按最终实际产出的 token 计入 TPM，请求结束后补扣。

# 2 模型默认额度与额度升降

每个API Key开通模型时，默认并发20、TPM 100w，apikey+模型独立限流，不挤占

申请提升额度：登录控制台 → 【在线咨询】 → 说明模型、期望并发/TPM、业务场景说明 → 平台技术支持人员会与您联系。

# 3 如何合理应对速率限制

我们建议开发者在系统设计中提前考虑以下策略

1. 控制并发与请求频率

• 使用请求队列或并发池

• 避免瞬时“洪峰式”请求

• 避免固定间隔的高频重试

2. 异步请求或批处理 API

• 非实时场景可通过批处理方式或异步请求降低并发压力（见批量推理部分）

# 4 常见问题

Q：429 等限流报错是否计费？

触发 429 限流报错的请求平台未实际处理，不计费；但 503 过载场景下若已部分处理，按实际消耗 token 计费。

Q：TPM 是按账户还是按 API Key 统计？

默认按 API Key + 模型分档统计。企业级客户可申请按 API Key / 项目维度拆分额度，见控制台「子账号配额」。

Q：流式请求的 token 如何计入 TPM？

按请求最终实际产出的总 token（输入 + 输出）在请求结束时一次性补扣，过程中不占用 TPM 槽位，但持续占用并发槽位直至流结束。

Q：不同模型是否共享额度？

不共享。各模型分档独立计算并发与 TPM，跨模型调用互不影响。