讯飞星火免费API申请教程：Spark Lite 不限调用量与实名要点

星火的主流调用方式是 WebSocket 长连接，请求体是一个 JSON，包含 header、parameter、payload 三段；鉴权信息拼在连接地址的 query 参数里，需要自己用 APISecret 做 HMAC-SHA256 签名。

接口地址与模型名

WebSocket 地址形如 wss://spark-api.xf-yun.com/v1.1/chat，对应 Lite 版本；其他版本路径不同，如 v3.1、v3.5、v4.0，具体以控制台已开通的服务和官方文档为准。模型通过请求体里的 domain 字段指定，Lite 对应 general，其余如 generalv3、generalv3.5、4.0Ultra 等需与已开通版本匹配。

如果控制台同时开通了 HTTP 兼容服务，也可以使用 OpenAI 风格地址 https://spark-api-open.xf-yun.com/v1，此时 model 填 lite、generalv3.5 这类名称，鉴权把 APIKey 与 APISecret 用冒号拼接后作为 Bearer 令牌。是否可用以控制台实际开通情况为准。

先看 HTTP 兼容方式的请求形态：

curl https://spark-api-open.xf-yun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的APIKey:你的APISecret" \
  -d '{"model":"lite","messages":[{"role":"user","content":"你好"}],"temperature":0.5,"max_tokens":1024,"stream":false}'

WebSocket 方式的完整签名与一次对话调用如下，运行前先安装依赖：

pip install websocket-client

import base64
import hashlib
import hmac
import json
from datetime import datetime
from urllib.parse import urlencode, urlparse

import websocket

APP_ID = "你的APPID"
API_KEY = "你的APIKey"
API_SECRET = "你的APISecret"

BASE_URL = "wss://spark-api.xf-yun.com/v1.1/chat"
parsed = urlparse(BASE_URL)
host = parsed.hostname
path = parsed.path

date = datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT")
sign_origin = "host: " + host + "\ndate: " + date + "\nGET " + path + " HTTP/1.1"
digest = hmac.new(API_SECRET.encode("utf-8"), sign_origin.encode("utf-8"), hashlib.sha256).digest()
signature = base64.b64encode(digest).decode("utf-8")

auth_origin = 'api_key="' + API_KEY + '", algorithm="hmac-sha256", headers="host date request-line", signature="' + signature + '"'
authorization = base64.b64encode(auth_origin.encode("utf-8")).decode("utf-8")

url = BASE_URL + "?" + urlencode({"authorization": authorization, "date": date, "host": host})

body = {
    "header": {"app_id": APP_ID, "uid": "demo_user"},
    "parameter": {"chat": {"domain": "general", "temperature": 0.5, "max_tokens": 1024}},
    "payload": {"message": {"text": [{"role": "user", "content": "用一句话介绍你自己"}]}},
}

ws = websocket.create_connection(url)
ws.send(json.dumps(body))

answer = ""
while True:
    resp = json.loads(ws.recv())
    if resp["header"]["code"] != 0:
        print("请求失败:", resp["header"]["code"], resp["header"].get("message"))
        break
    choices = resp["payload"]["choices"]
    answer = answer + choices["text"][0]["content"]
    if choices["status"] == 2:
        break

ws.close()
print(answer)

注意 header.uid 只是用户标识，填任意字符串即可；payload.message.text 是消息数组，多轮对话要把历史消息按先后顺序放进去。

关键参数说明

• header.app_id：控制台里的 APPID，不是 APIKey。
• parameter.chat.domain：模型版本标识，Lite 用 general，与已开通服务不一致会直接报错。
• parameter.chat.temperature：随机性，取值 0 到 1，问答类场景建议 0.1 到 0.5。
• parameter.chat.max_tokens：单次回复的最大生成长度，设得太小会出现回答被截断。
• payload.message.text：消息数组，每项含 role（user 或 assistant）与 content。
• 流式返回时按 payload.choices.status 判断是否结束，等于 2 表示本次生成完毕。

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

连接建立后服务端会在 header.code 返回非 0 值并附带 message，提示通常集中在鉴权失败、额度不足或有效期已过、请求频率超限这几类；HTTP 兼容方式则表现为 401、403 或 429 状态码。排查按下面顺序走，能覆盖绝大多数情况。

1. 核对三个凭证：APPID、APIKey、APISecret 是否与当前应用一致，是否误用了其他应用的密钥。
2. 核对签名串：date 必须是 GMT 格式且与本机时间偏差不大，签名原文里 host、date、request-line 三段的顺序不能改。
3. 核对地址与 domain：连接路径里的版本号要和已开通服务对应，domain 不能填成未开通的模型。
4. 登录控制台查看免费额度剩余量与有效期，赠送 tokens 过期后调用会直接失败，需要重新领取或改用其他服务。
5. 若提示频率或并发超限，降低调用速率、减少并发连接后重试，免费档的并发通常较低。
6. 最后检查消息长度与 max_tokens 是否超过该模型的上下文上限，以及本机网络、代理是否拦截了 WebSocket 连接。