讯飞星辰 MaaS 平台免费额度申请：Spark-X2.6 十亿 tokens 领取与调用教程

讯飞星辰 MaaS 的在线推理接口兼容 OpenAI 的对话补全协议，只要把 base_url、密钥和模型名换成平台给出的值，原本基于 OpenAI SDK 的代码基本可以直接运行。

base_url 与模型名

base_url 形如 https://maas-api.cn-huabei-1.xf-yun.com/v1，请以控制台「在线推理」或「调用示例」页面复制的地址为准，注意末尾要带 /v1。模型 ID 同样在模型列表里复制，Spark-X2.6 活动期间对应的具体 ID 字符串以控制台实际显示为准；DeepSeek、GLM、MiniMax、Kimi 等第三方模型各有独立的 ID。

一次对话补全调用

先把密钥放进环境变量，不要硬编码进代码：

export XF_MAAS_API_KEY="你的密钥"

再用 curl 发起一次最小可用的请求：

curl https://maas-api.cn-huabei-1.xf-yun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XF_MAAS_API_KEY" \
  -d '{
    "model": "Spark-X2.6",
    "messages": [
      {"role": "system", "content": "你是一名简洁的技术助手。"},
      {"role": "user", "content": "用一句话解释什么是 MaaS。"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'

关键参数说明：model 填控制台给出的模型 ID；messages 是角色消息数组，system 用来设定风格与约束，user 是提问，多轮对话按顺序追加历史消息即可；temperature 控制随机性，取值靠近 0 时输出更稳定；max_tokens 限制单次输出长度，也是控制赠额消耗的主要开关；stream 设为 true 时服务端会按 SSE 分块返回，适合做网页端的打字机效果。

在 Python 中改用 OpenAI 兼容 SDK 的写法如下：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XF_MAAS_API_KEY"],
    base_url="https://maas-api.cn-huabei-1.xf-yun.com/v1",
)

resp = client.chat.completions.create(
    model="Spark-X2.6",
    messages=[{"role": "user", "content": "你好，简单介绍一下你自己"}],
    temperature=0.7,
    max_tokens=512,
)
print(resp.choices[0].message.content)

额度耗尽与限流的典型表现

• 返回 401 或 403：密钥错误、已被删除，或账号尚未完成实名。重新复制密钥并确认前后没有多余空格，再检查实名状态。
• 返回 404 或提示模型不存在：多半是 base_url 少了 /v1，或者模型 ID 拼写有误。回控制台重新复制完整地址和模型名。
• 返回 429 或提示请求过于频繁：触发了每分钟请求数或每分钟 tokens 的限流阈值。降低并发，并在代码里加指数退避重试。
• 提示余额不足或赠额已过期：赠额用完或超出了活动有效期。到额度管理页核对剩余量与到期时间，第三方模型不参与赠额时也会出现同样报错。

排查时建议按「密钥是否正确 → base_url 是否完整 → 模型 ID 是否存在 → 额度余额与有效期 → 限流阈值」的顺序逐项排除，绝大多数报错在前三步就能定位。