讯飞星火 API 怎么调用？开发者接入完整教程

接 AI 大模型 API，星火可能是国内最划算的入门选择

你想在自己的项目里加一个 AI 助手、写一个微信机器人、给客户做个内部聊天工具——选哪家 API 是第一道难题。讯飞星火给个人开发者的待遇相当友好：Lite 版永久免费，Pro / Max 版个人 200 万 tokens 免费额度有效期 12 个月，每个模型再独立赠送 20 万。对小项目来说，几乎等于「白送」。

下面这篇 2500 字教程会带你从零接入：注册开放平台 → 创建应用拿 appid → 选模型版本 → 跑通 Python 第一个请求 → 处理常见错误 → 上生产前的注意事项。开发者向，但 0 基础也能跟下来。

如果你还在选模型阶段、不确定该不该用星火，可以先看 讯飞星火和 DeepSeek 哪个好 这篇 10 维度对比再回来。

用哪个：Web API vs SDK 怎么选

讯飞星火 API 有两条主要接入路径，刚开始很容易选错：

新手强烈推荐从 Web API 入手。后端有什么语言都能调，文档最全，社区参考代码最多。下面教程默认走这条路。

第 1 步：注册讯飞开放平台

讯飞星火的 API 不在星火 App 里申请，而是在讯飞开放平台（xfyun.cn）。这是两个独立的后台，账号互通但功能不一样：

• xinghuo.xfyun.cn：星火的 C 端 App（聊天、写作、画图等）
• xfyun.cn：开放平台（拿 API key、看用量、买套餐）

去 xfyun.cn 注册（用之前注册星火的手机号就行，不需要重新注册）。如果还没注册过任何讯飞账号，先看 讯飞账号注册教程。

注册完成后会让你做实名认证。个人开发者用身份证认证就行，企业开发者需要营业执照（额度更大）。

第 2 步：创建应用拿 appid

登录 xfyun.cn 后：

1. 右上角点头像 → 进入「控制台」
2. 左侧找「我的应用」 → 点「创建新应用」
3. 填写应用信息：
   • 应用名称：随便起，比如「我的聊天机器人」
   • 应用分类：选「AI 大模型」
   • 应用平台：选你打算用的（Web / Android / iOS / Windows）
   • 应用功能描述：一句话说清楚
4. 提交后立即拿到三个核心凭证：
   • APPID：应用 ID
   • APISecret：API 密钥
   • APIKey：API key

这三个值就是你接入星火 API 的全部凭证，找个地方记好。后面的代码都要用。

第 3 步：开通星火大模型服务

拿到 APPID 后，还要单独给这个应用「开通」星火大模型服务：

1. 还在控制台 → 左侧找「星火大模型」（或叫「Spark」）
2. 选你要用的模型版本：
   • Spark Lite：免费，能力基础，适合简单对话
   • Spark Pro：付费，能力均衡，日常推荐
   • Spark Max：付费，旗舰版，复杂任务
   • Spark X1：付费，深度推理版本，对标 DeepSeek R1
3. 点「立即领取」拿到对应免费额度（每个模型独立赠送 20 万 tokens）
4. 服务详情页会显示「Service URL」——这是你 API 调用的 endpoint，比如：
   • Spark Lite: wss://spark-api.xf-yun.com/v1.1/chat
   • Spark Pro: wss://spark-api.xf-yun.com/v3.1/chat
   • Spark Max: wss://spark-api.xf-yun.com/v3.5/chat

每个版本的 URL 路径不同，调用时要对应填好。

第 4 步：跑通第一个 Python 请求

讯飞星火 API 是 WebSocket 流式协议，鉴权方式偏复杂（要拼 URL + HMAC-SHA256 签名）。最快的做法是直接装官方推荐的第三方 SDK：

pip install spark_ai_python websocket-client

下面是一个能直接跑的最小示例（用 Spark Pro）：

import json
import hmac
import hashlib
import base64
import websocket
import _thread as thread
from datetime import datetime
from time import mktime
from wsgiref.handlers import format_date_time
from urllib.parse import urlparse, urlencode

# 填你自己的三个凭证
APPID = "你的_APPID"
API_KEY = "你的_APIKey"
API_SECRET = "你的_APISecret"
SPARK_URL = "wss://spark-api.xf-yun.com/v3.1/chat"
DOMAIN = "generalv3"

def create_url():
    host = urlparse(SPARK_URL).netloc
    path = urlparse(SPARK_URL).path
    now = datetime.now()
    date = format_date_time(mktime(now.timetuple()))
    signature_origin = f"host: {host}\ndate: {date}\nGET {path} HTTP/1.1"
    signature_sha = hmac.new(
        API_SECRET.encode(), signature_origin.encode(), hashlib.sha256
    ).digest()
    signature_sha_b64 = base64.b64encode(signature_sha).decode()
    auth_origin = (
        f'api_key="{API_KEY}", algorithm="hmac-sha256", '
        f'headers="host date request-line", signature="{signature_sha_b64}"'
    )
    auth = base64.b64encode(auth_origin.encode()).decode()
    params = {"authorization": auth, "date": date, "host": host}
    return SPARK_URL + "?" + urlencode(params)

def on_message(ws, msg):
    data = json.loads(msg)
    code = data["header"]["code"]
    if code != 0:
        print(f"请求失败: code={code}, message={data['header']['message']}")
        ws.close()
        return
    choices = data["payload"]["choices"]
    text = choices["text"][0]["content"]
    print(text, end="", flush=True)
    if choices["status"] == 2:
        ws.close()

def on_open(ws):
    payload = {
        "header": {"app_id": APPID},
        "parameter": {"chat": {"domain": DOMAIN, "temperature": 0.7}},
        "payload": {"message": {"text": [
            {"role": "user", "content": "用一句话介绍讯飞星火"}
        ]}},
    }
    ws.send(json.dumps(payload))

if __name__ == "__main__":
    ws = websocket.WebSocketApp(
        create_url(),
        on_message=on_message,
        on_open=on_open,
    )
    ws.run_forever()

把三个凭证填好，运行这个脚本，你会看到星火流式吐出一段话。这就是你第一个能跑的星火 API 请求。

不同模型版本对应不同 DOMAIN：

• Lite：general
• Pro (v3.1)：generalv3
• Max (v3.5)：generalv3.5
• X1：x1

把 SPARK_URL 和 DOMAIN 换成对应版本就能切换模型。

第 5 步：用 OpenAI 兼容协议（更省事的新选择）

如果你已经在用 OpenAI SDK 写代码，讯飞星火现在也支持 OpenAI 协议兼容接入，写法跟调用 ChatGPT 一模一样：

from openai import OpenAI

client = OpenAI(
    api_key="你的_APIPassword",  # 在控制台单独申请
    base_url="https://spark-api-open.xf-yun.com/v1/",
)

resp = client.chat.completions.create(
    model="generalv3.5",
    messages=[{"role": "user", "content": "用一句话介绍讯飞星火"}],
    stream=True,
)

for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

OpenAI 兼容协议在控制台需要单独申请 APIPassword，但好处是所有原本用 OpenAI 写的代码改两行就能切到星火，迁移成本几乎为零。新项目推荐直接走这条路。

万能调试 prompt（让 AI 帮你写接入代码）

如果你自己不熟悉 Python 或者要用其他语言（Node / Go / Java），下面这个 prompt 直接喂给 ChatGPT / DeepSeek / 星火自己，让它帮你写：

你是一位资深后端工程师。请帮我写一段「编程语言」代码，调用讯飞星火大模型 API。
需求：

模型版本：「Spark Pro / Max / X1」
接入方式：「原生 WebSocket / OpenAI 兼容协议」
调用方式：「流式 stream / 一次性返回」
业务场景：「客服回答 / 文章生成 / 翻译 / 其他」
我已经有的凭证：

APPID = … (我自己填)
APIKey = …
APISecret = …
如果用 OpenAI 协议，还有 APIPassword = …
要求：

给完整可运行的代码
鉴权部分注释清楚每一步在干什么
处理常见报错：401 鉴权失败、429 限速、10000 系列业务错误
给一个测试用的 main 函数
标出哪些参数（temperature / max_tokens / top_k）可以调
不要用 mock 数据，按真实可调通的实现写。

计费、免费额度、并发限制（不看会爆账单）

接 API 前一定搞清楚下面 4 件事：

1. 免费额度

• 个人开发者：每个模型独立赠送 20 万 tokens，有效期 12 个月
• 整体平台还有 200 万 tokens 通用额度
• 企业开发者：500 万 tokens

对个人小项目，200 万 tokens 大约够：

• 短对话：1 万次
• 长篇文章生成：5000 篇 800 字
• 代码生成：500 次复杂任务

2. 付费单价

• Spark Lite：永久免费
• Spark Pro：约 0.21 元 / 万 tokens
• Spark Max：约 0.21 元 / 万 tokens（输入输出分开计）
• Spark X1：单价更高，深度推理型

实际单价会随官方调整，调用前去控制台「计费说明」看最新。

3. 并发上限

默认所有用户最大并发 20 路。这是硬限制——你同时发起的请求数不能超过 20，超了会返回 10907 错误。

如果业务需要更高并发（比如你的 App 同时有 100 个用户在聊），要去控制台申请「QPS 扩容」。

4. token 怎么算

讯飞按「输入 + 输出 token 总和」计费，每 1 小时结算一次扣费。token 数量计算大致：

• 中文：1 个汉字 ≈ 1.5 token
• 英文：1 个单词 ≈ 1.3 token
• 标点和换行也算

每次请求记得加 max_tokens 限制，避免 AI 跑飞输出几万字烧光额度。

5 个最常见的报错和救命方案

遇到没见过的错误码，去 xfyun.cn 文档中心搜「错误码」有完整列表。

上生产前必须做的 4 件事

1. 加重试机制：网络抖动 + 10110 是常态，至少三次指数退避重试
2. 加超时控制：WebSocket 长连接默认无超时，建议设 30 秒兜底
3. 加 token 监控：每次请求记录消耗的 token，超过预算阈值报警
4. 隔离测试和生产 appid：不要用同一个 key 跑测试和线上业务，否则配额混淆

接下来可以做什么

讯飞星火 API 跑通后，你可以做的方向很多：

• 讯飞星火智能体怎么创建：用 API 之外，星火本身有 Agent 平台，零代码也能搭机器人
• 讯飞星火 prompt 公式：API 调用效果好不好，七成靠 prompt
• 讯飞星火完全指南：八大功能里哪些可以通过 API 接出来
• AI 智能体教程：搭好 API 之后做更复杂的 Agent 应用

最后一句话提醒：API 接入是工程问题，prompt 才是产品问题。能调通是第一步，但你的产品能不能用得舒服、回答质量稳不稳定，靠的是 prompt 工程和场景设计。先用免费额度跑通 demo，再考虑加预算上生产。