讯飞星火apikey怎么申请与调用？一份实战避坑指南
去年底我接手一个智能硬件的语音助手改造项目，客户明确要求用国产大模型，理由是数据不出境、备案好过。横向测了三家之后，最后落在讯飞星火上——G端和B端的合规适配确实省心，Lite 版本的免费额度也够撑完整个 POC。
但真正开始写代码的第二天，我就卡住了。控制台页面上并排躺着 APPID、APIKey、APISecret 三个字段，我拿着 APIKey 去填 OpenAI SDK 的 `api_key` 参数，返回 401。折腾了小半天才搞明白：讯飞星火apikey从来不是"一把钥匙"那么简单。
这篇文章把我踩过的坑和最终跑通的方案完整摊开，包括两套鉴权机制的区别、三段可直接运行的代码，以及上线前必须处理的并发和额度问题。
核心结论摘要：讯飞星火apikey是 APPID、APIKey、APISecret 三个凭证的组合，而非单一密钥。调用分两条路——OpenAI 兼容的 HTTP 接口直接用 APIPassword，原生 WebSocket 接口则需 HMAC-SHA256 动态签名。新手先走 HTTP，半小时能跑通。
二、两套鉴权机制拆解：为什么星火要设计两条路
这个问题的答案，其实藏在产品演进的节奏里。讯飞最早只有原生 WebSocket 接口，因为流式返回（一个字一个字往外蹦）是对话类产品的刚需，而 2023 年那会儿 HTTP 流式还不成熟。后来为了兼容存量生态，才补了一套 OpenAI 协议的 HTTP 端点。
两条路的差别，直接决定了你该选哪条：
| 维度 | OpenAI 兼容 HTTP | 原生 WebSocket | |---|---|---| | 端点 | `spark-api-open.xf-yun.com/v1` | `spark-api.xf-yun.com/v3.5/chat` | | 鉴权材料 | APIPassword | APPID + 动态签名 | | 流式支持 | 支持（SSE） | 原生支持，延迟更低 | | 多模态 | 部分模型支持 | 图片理解能力更完整 | | 迁移成本 | 改 base_url 即可 | 需要重写通信层 |
我的建议很直接：如果你只是想验证效果、或者手上已经有一堆 OpenAI 格式的代码，走 HTTP。如果你要做实时语音对话、需要极致首字延迟，或者要用多模态大模型能力，老老实实上 WebSocket。
三、讯飞星火apikey使用教程：从申请到跑通第一次大模型推理
第一步：创建应用并开通模型服务
到 xfyun.cn 注册账号，完成实名认证（个人身份证就行），然后在控制台"创建应用"。填个名称、选个行业分类，提交后 APPID、APIKey、APISecret 就会出现在应用详情页。
这里有个新手必踩的坑：创建应用不等于开通模型。你还需要进到"星火认知大模型"服务页面，手动为这个应用开通对应的版本（Lite / Pro / Max / 4.0Ultra）。我当初就是漏了这步，代码没错、密钥没错，但一直返回授权失败，白白排查了四十分钟。
第二步：用 HTTP 接口跑通第一次大模型推理
依赖：pip install openai
from openai import OpenAI
client = OpenAI(
控制台"星火认知大模型"页面生成的 APIPassword，格式固定为 "APIKey:APISecret"
api_key="你的APIPassword", base_url="https://spark-api-open.xf-yun.com/v1" # 注意结尾的 /v1 不能少 )
resp = client.chat.completions.create( model="4.0Ultra", # 可选 lite / generalv3.5 / max-32k / 4.0Ultra，以控制台可选项为准 messages=[ {"role": "system", "content": "你是一位严谨的技术助理"}, {"role": "user", "content": "用三句话解释什么是大模型推理"} ], stream=False )
打印模型返回的文本
print(resp.choices[0].message.content)
这段代码我在本地 Python 3.11 + openai 1.30.0 上验证过，能直接出结果。如果你习惯用 requests 裸调，把 `Authorization: Bearer {APIPassword}` 塞进 header 也行，效果一样。
第三步：需要流式输出时切到 WebSocket
做实时对话的时候，HTTP 那种"等全文生成完再返回"的体验是不能接受的。这时候得回到原生接口：
依赖：pip install websocket-client
import hashlib, hmac, base64, json, ssl from datetime import datetime from urllib.parse import urlencode, urlparse import websocket
APPID = "你的APPID" API_KEY = "你的APIKey" API_SECRET = "你的APISecret" URL = "wss://spark-api.xf-yun.com/v3.5/chat" # 域名里的版本号要和 domain 参数对齐
def build_auth_url(url: str) -> str: """按官方规范