讯飞星火 API 接入说明与能力概览

2026-07-24

讯飞星火（Spark）是科大讯飞推出的大语言模型，凭借科大讯飞在语音识别领域的深厚积累，在语音+文本多模态融合、教育类场景和方言理解方面有独特优势。Spark 系列最新版提供 OpenAI 兼容 HTTP 接口，同时保留传统 WebSocket 接口，适合不同技术栈的开发者接入。

如果你是第一次接触讯飞开放平台，先说一个容易踩的坑：讯飞的产品线很杂，除了星火大模型，控制台里还挂着语音识别、语音合成、OCR 这些老牌能力，界面入口经常改版。你要找的是”星火认知大模型”这个具体产品下的应用，不要在通用的语音类应用里申请 Key，那样拿到的凭证调不通 Spark 的 Chat 接口，会一直报鉴权失败，排查半天才发现是入口找错了。

注册与获取 API Key

访问 xinghuo.xfyun.cn 或开放平台注册账号；
进入控制台 → 我的应用 → 创建应用，获取 APPID、APIKey、APISecret；
新版 OpenAI 兼容接口只需 APIKey；旧版 WebSocket 鉴权需要三者组合生成签名；
控制台提供额度查看与充值入口，新用户有免费 token 赠送。

这三个凭证的关系你得搞清楚，不然容易用错：APPID 标识的是你这个应用本身，APIKey 相当于用户名，APISecret 相当于密码，旧版接口需要三者一起做签名运算；新版 OpenAI 兼容接口做了简化，直接把 APIKey 当 Bearer Token 用，不再需要签名这一步，这也是官方现在主推新接口的原因——接入成本从”要写一套 HMAC 签名逻辑”降到”改一个 base_url”。企业实名认证通过之后再申请应用，额度和调用权限会比个人账号宽松不少，如果你打算接生产环境，建议提前把企业认证走完，别等上线前一天才发现认证要审核好几天。

接入示例：OpenAI 兼容调用（推荐）

Spark Pro 及以上版本支持 OpenAI 兼容 HTTP 接口：

from openai import OpenAI

client = OpenAI(
    api_key="your-spark-api-key",
    base_url="https://spark-api-open.xf-yun.com/v1",
)

response = client.chat.completions.create(
    model="generalv3.5",                     # Spark Max 对应的模型标识
    messages=[
        {"role": "system", "content": "你是一个专业的教育内容创作助手"},
        {"role": "user", "content": "为小学三年级学生写一道关于分数的应用题"},
    ],
)
print(response.choices[0].message.content)

这段代码看着和调用 OpenAI 官方 SDK 没什么区别，这正是”OpenAI 兼容”的价值所在——你不需要为每家国产模型单独学一套 SDK，换 base_url 和 api_key 就能把已有的调用逻辑迁移过来。这里有个新手常踩的坑：model 字段填的不是”Spark Max”这种展示名，而是 generalv3.5 这种接口标识，两者对不上号是讯飞产品命名历史遗留问题（早期版本号和现在的市场名称不是一一对应关系）。建议你写代码时把模型标识和对应的市场名称做成一个常量映射表放在配置文件里，不要在业务代码里硬编码字符串，不然哪天讯飞调整了标识命名，你要满仓库去找魔法字符串。

另外 system 角色的提示词在 Spark 上是真的有效的，实测对输出风格的约束力不弱，如果你的场景需要模型保持固定人设或输出格式，把规则写进 system prompt 比在 user 消息里反复强调更稳。

流式输出：

stream = client.chat.completions.create(
    model="generalv3.5",
    messages=[{"role": "user", "content": "解释神经网络反向传播的原理"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

注意 if chunk.choices[0].delta.content: 这一行判断不是多余的防御性代码，是必须要有的：流式响应的第一个 chunk 和最后一个 chunk，delta.content 大概率是 None 而不是空字符串，直接 print(None, end="") 会在控制台打出一串 None 字符，很多人调流式接口第一次跑通时都被这个恶心过。如果你要把流式结果实时推给前端，建议在这一层就把 None 过滤掉，不要指望前端再做一次判断。

生产环境用流式接口还有两个容易被忽略的点：一是 SSE 连接本质上是一条长连接，你的 HTTP 客户端（比如 httpx、requests）默认超时时间可能只有几十秒，如果模型生成较长内容耗时超过这个值，连接会被客户端自己掐断，报的错误往往是 ReadTimeout 而不是服务端返回的错误码，第一次遇到很容易怀疑错方向，去查讯飞那边的服务状态；正确做法是把超时单独调大，或者用支持流式读取超时豁免的客户端配置。二是网关和反向代理（比如公司内网的 Nginx）如果开了 proxy_buffering，会把流式响应先攒一批再转发，表现出来就是”流式接口用起来跟非流式一样卡顿再一次性吐出来”，这不是讯飞的问题，是你自己的代理层把流给”拍平”了，需要在 Nginx 配置里对这条路径关掉缓冲。

Spark 主要模型对比

模型版本	API 标识	上下文	定位
Spark4.0 Ultra	`4.0Ultra`	8k tokens	旗舰，最强综合能力
Spark Max	`generalv3.5`	8k tokens	均衡旗舰
Spark Pro	`generalv3`	8k tokens	生产级通用
Spark Lite	`lite`	4k tokens	免费轻量版
Spark Pro-128k	`pro-128k`	128k tokens	长上下文

选择建议：最高质量任务用 4.0Ultra；常规生产用 generalv3.5（Spark Max）；开发测试免费用 lite；长文档场景选 pro-128k。

这几个版本的取舍逻辑我再拆细一点。如果你在做一个内部工具或者验证 demo，先用 lite 把整条链路跑通，包括错误处理、重试逻辑、日志记录，这些东西和用哪个模型版本无关，没必要一上来就用旗舰版消耗额度去调试。等链路稳定了，再切到 generalv3.5 做效果对比，大部分中文问答、内容生成、教育场景用 Max 就够用，真没必要为了”用最好的模型”去承担 4.0Ultra 的成本溢价——除非你的任务对推理深度、复杂指令遵循要求特别高，比如多步骤逻辑推理、长链条数学题，这种场景旗舰版和均衡版的差距才会明显拉开。pro-128k 这个版本容易被忽略，但如果你要做的是长文档摘要、多轮长对话记忆、代码库级别的问答，8k 上下文很快就会因为超出窗口而报错或者被截断，这时候别硬扛着用 8k 版本反复裁剪 prompt，直接换 pro-128k 省事得多。

核心特色能力

语音+文本融合：依托科大讯飞 ASR（语音识别）和 TTS（语音合成）能力，可构建端到端语音对话应用；
教育场景优化：在数学解题步骤、作文批改、知识点讲解等教育任务上有专项优化；
方言与多语种：科大讯飞语音技术支持多种方言，结合星火可构建方言理解应用；
讯飞开放平台生态：与 OCR、语音、情感识别等 AI 能力共享同一平台账号。

这里要提醒一句实际使用中的落差：星火在营销宣传里强调”多模态”，但你在用 Chat Completions 这套 OpenAI 兼容接口时，输入端目前主要是文本，不要默认它和 GPT-4o 那种能直接塞图片进 messages 的多模态接口是同一回事。语音方面的融合，实际做法是你自己调讯飞的 ASR 接口把语音转成文字，再把文字丢给 Spark 处理，回复再走 TTS 转成语音——这是拼接起来的一条流水线，不是模型本身原生吃音频输入。搞清楚这一点，你在设计系统架构的时候就知道要预留 ASR/TTS 这两个独立调用节点，而不是指望一个接口全包圆。

价格定性

截至 2026-06，以官方公示为准：

Spark Lite 完全免费，适合开发阶段测试；
Spark Pro 和 Max 处于中等价位区间；
Spark 4.0 Ultra 旗舰版高于其他版本；
教育和 ToB 企业合作可联系商务获取专项定价。

具体单价以讯飞星火价格页为准，也可用价格对比工具横向比较。

成本这块给你一个估算思路，不用死记单价数字：先拿一批真实业务样本（比如你产品里最常见的 10 条用户输入）跑一遍，统计平均 prompt_tokens 和 completion_tokens，再乘以预估日调用量，就能算出大致的日消耗规模。很多团队上线前只测了几条短样本就估算成本，上线后发现真实用户的输入比测试样本长得多（尤其是带上下文历史的多轮对话，历史消息会重复计入每次请求的 prompt_tokens），成本直接翻倍。多轮对话场景建议做上下文裁剪，只保留最近几轮加一个摘要，而不是无脑把全部历史塞进每次请求。

常见问题

旧版 WebSocket 接口和新版 HTTP 接口有什么区别？ 旧版 WebSocket 接口需要 APPID + APIKey + APISecret 组合进行 HMAC-SHA256 签名鉴权，实现较复杂；新版 OpenAI 兼容 HTTP 接口只需 Bearer API Key，与 OpenAI SDK 完全兼容，强烈推荐新项目使用新版接口。旧接口仍在维护但不再推荐。

如果你维护的是历史项目，绕不开旧版鉴权，这里给你一个原理性的实现思路，帮你理解签名到底在签什么、错在哪一步：

import hmac, hashlib, base64
from email.utils import formatdate

def build_authorization(host, path, api_key, api_secret):
    date = formatdate(timeval=None, localtime=False, usegmt=True)
    # 把 host、date、请求行拼成待签名字符串
    signature_origin = f"host: {host}\ndate: {date}\n{path} HTTP/1.1"
    signature_sha = hmac.new(
        api_secret.encode("utf-8"),
        signature_origin.encode("utf-8"),
        digestmod=hashlib.sha256,
    ).digest()
    signature = base64.b64encode(signature_sha).decode("utf-8")
    authorization_origin = (
        f'api_key="{api_key}", algorithm="hmac-sha256", '
        f'headers="host date request-line", signature="{signature}"'
    )
    return base64.b64encode(authorization_origin.encode("utf-8")).decode("utf-8")

核心思路是：用 APISecret 作为密钥，对 host + date + 请求行 这三行拼出来的字符串做 HMAC-SHA256，再套一层 base64 得到最终签名，APIKey 只是标识不参与加密运算。实操中最容易翻车的是这几处细节：日期必须是 GMT 格式的 HTTP 标准时间，且和请求发出的时刻要在允许的时间误差窗口内，服务器时钟漂太多会直接鉴权失败；拼接字符串里的换行符、大小写、字段顺序必须和文档要求完全一致，差一个空格签名就对不上，报错信息通常只提示”签名错误”，不会告诉你具体错在哪个字符上。所以真到要接旧接口的时候，务必对着官方最新文档逐字核对字段名和格式，这几年讯飞的文档细节改过几次，网上流传的旧代码片段不一定还能直接用。

Spark Lite 免费版有请求限制吗？ 有并发和每日调用次数限制，具体配额以控制台页面显示为准。对于轻量测试和个人开发者来说通常足够，生产环境建议升级到付费版本。如果你在压测阶段发现请求老是被拒，报错类似 HTTP 429（请求过多）或者响应体里带有限流相关的错误码，先别急着怀疑账号出问题，大概率就是免费额度的并发或频率上限打满了——解决办法要么把请求节流（加个简单的令牌桶或者 asyncio.Semaphore 控制并发数），要么直接升级付费版本换更高配额，两条路都比反复重试硬冲限流来得靠谱。如果遇到的是 HTTP 401，先检查是不是把 APIKey 当成了新版接口要求的完整格式（有的团队习惯性地把旧版三段式凭证整体传进去，新版接口只认单独的 APIKey），这个错误占了新手接入报错里的很大一部分。

生产环境调用建议加一层重试退避逻辑，简单可靠的写法是指数退避加随机抖动：

import time, random

def call_with_retry(func, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            # 指数退避 + 随机抖动，避免多个请求在同一时刻集体重试
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)

这段逻辑只对”可重试”的错误生效才有意义，比如网络抖动、429 限流、5xx 服务端错误；对于 401 鉴权失败这种确定性错误，重试没有任何意义，只会浪费时间还可能触发更严格的风控，应该直接在捕获异常时判断错误类型，鉴权类错误立刻抛出终止，不要塞进重试循环里。

讯飞星火适合做教育类应用吗？ 适合。科大讯飞在教育行业深耕多年，星火模型在教学内容生成、习题讲解、批改作文等任务上有专项优化，结合讯飞开放平台的语音能力可构建完整的教育 AI 应用。实际落地时有个经验值得分享：教育场景对输出的准确性和可控性要求比一般对话场景高得多，尤其是数学解题这类任务，建议在 system prompt 里明确要求模型分步展示推理过程而不是直接给答案，一方面便于人工抽检发现模型出错的具体环节，另一方面分步输出本身也更符合教学场景的需求。批改作文这类主观性任务，最好搭配人工复核机制，模型给出的评分和修改建议作为老师批改的辅助参考，而不是直接替代人工判分，这既是效果考虑，也是很多教育类产品在合规和责任划分上的普遍做法。

分类导航：国产模型专题

实用工具：价格对比工具 · Token 计数器