硅基流动 API 怎么用？从 API Key 到第一次调用

硅基流动 API 接入并不复杂。第一次调用只需要准备三项配置：

• 在硅基流动控制台创建的 API Key；
• Base URL：https://api.siliconflow.cn/v1；
• 从当前模型列表复制的完整模型 ID。

最容易出错的也正是这三项：环境变量没有生效、Base URL 仍指向其他平台，或者模型 ID 已经变化。下面先跑通一个最小调用，再解释怎样排错和改造成可长期运行的代码。

如果还没有硅基流动账号，可以先完成注册，再回来继续配置 API。

一、创建并保存 API Key

登录硅基流动控制台，进入“API 密钥”页面，新建一个 API Key。完整密钥只用于程序鉴权，不要写入代码、Markdown、聊天记录或 Git 仓库。

在 PowerShell 中，可以先把密钥放进当前终端的环境变量：

$env:SILICONFLOW_API_KEY="你的 API Key"

关闭这个 PowerShell 窗口后，变量就会失效，适合第一次测试。长期部署时应改用服务器环境变量或专门的密钥管理工具。

可以先确认变量是否存在，但不要打印密钥本身：

if ($env:SILICONFLOW_API_KEY) {
    "SILICONFLOW_API_KEY 已设置"
} else {
    "SILICONFLOW_API_KEY 未设置"
}

二、先查询当前账号可用的模型

教程里写死的模型名称可能过期。硅基流动提供 GET /v1/models 接口，用当前账号的 API Key 可以取得可用模型列表。

import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen

api_key = os.environ["SILICONFLOW_API_KEY"]
query = urlencode({"type": "text"})
request = Request(
    f"https://api.siliconflow.cn/v1/models?{query}",
    headers={"Authorization": f"Bearer {api_key}"},
)

with urlopen(request, timeout=30) as response:
    models = json.load(response)["data"]

for item in models[:20]:
    print(item["id"])

从输出中选择一个当前账号可用的文本模型，把完整 ID 保存到另一个环境变量：

$env:SILICONFLOW_MODEL="从模型列表复制的完整模型 ID"

不要随意省略模型名前面的组织名，也不要把网页上的展示名称当作 API 模型 ID。

三、使用 OpenAI Python SDK 完成第一次调用

硅基流动的部分大语言模型可以通过 OpenAI Python SDK 调用。先安装或升级 SDK：

python -m pip install --upgrade openai

新建一个测试脚本：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SILICONFLOW_API_KEY"],
    base_url="https://api.siliconflow.cn/v1",
    timeout=60.0,
)

response = client.chat.completions.create(
    model=os.environ["SILICONFLOW_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "只回复一句话：硅基流动 API 调用成功。",
        }
    ],
    max_tokens=128,
    extra_body={"enable_thinking": False},
)

print(response.choices[0].message.content)
print("model:", response.model)
print("usage:", response.usage)

运行后应重点检查三项：

1. 返回内容不为空；
2. response.model 对应本次实际调用的模型；
3. response.usage 中存在输入、输出和总 Token 用量。

如果程序成功返回，说明 API Key、Base URL、模型 ID 和基础网络路径已经连通。返回文案本身并不重要。

本文的真实调用结果

2026 年 8 月 29 日，本文使用项目专用 API Key 和 OpenAI Python SDK 3.5.0 完成了两轮验证：

因此，示例显式关闭了思考模式。对于不支持该参数的模型，可以删除 extra_body；如果需要模型输出思考过程，则应提高 max_tokens 并单独处理 reasoning_content。

四、需要边生成边显示时使用流式输出

对回答较长的任务，流式输出可以更早显示首段内容。硅基流动官方文档也建议在部分 503、504 场景下尝试流式请求。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SILICONFLOW_API_KEY"],
    base_url="https://api.siliconflow.cn/v1",
    timeout=60.0,
)

stream = client.chat.completions.create(
    model=os.environ["SILICONFLOW_MODEL"],
    messages=[
        {"role": "user", "content": "用三点说明什么是向量数据库。"}
    ],
    max_tokens=512,
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)

流式输出改善的是等待体验，不代表请求不会失败。生产代码仍需设置超时、处理异常并限制重试次数。

五、调用失败时按这个顺序检查

400：请求参数不正确

先读取接口返回的 message。常见原因包括模型 ID 不存在、字段类型错误、参数不被当前模型支持。不要只看 HTTP 状态码就盲目重试。

401：API Key 设置不正确

依次检查：

1. 当前进程是否真的读到了 SILICONFLOW_API_KEY；
2. Key 是否属于硅基流动中文站；
3. base_url 是否准确写成 https://api.siliconflow.cn/v1；
4. Key 是否已经被删除或停用。

不要通过打印完整 Key 来排错。

402：账户欠费

检查账户余额、代金券适用范围和当前模型的计费状态。免费模型、代金券和现金余额不是同一个概念，最终以控制台显示为准。

403：权限不足

官方说明中，常见原因是当前账号没有对应模型权限，或模型要求实名认证。先查看错误消息，再核对账号状态和模型访问条件。

429：触发 Rate Limits

根据错误消息判断触发的是请求次数还是 Token 相关限制。程序应降低并发，并使用带随机抖动的指数退避；不要在收到 429 后立即无限重试。

503、504：服务负载或请求超时

可以稍后进行有限重试，或对适合的任务改用流式输出。关键业务还应准备备用模型，而不是把所有请求固定在一个模型上。

六、接入真实项目之前再补四项

最小示例只证明“能调用”，不能直接代表已经适合生产环境。

1. 把模型 ID 变成配置

模型会更新、调价或下线。使用环境变量或配置中心管理模型 ID，避免散落在多份代码中。

2. 只重试适合重试的错误

400、401、402、403 通常需要先修正参数、密钥、余额或权限；429、503、504 才适合在限制次数的前提下等待后重试。

3. 记录请求证据，但不记录敏感内容

建议记录调用时间、模型 ID、耗时、Token 用量、HTTP 状态和平台返回的追踪 ID。不要记录 API Key，也不要默认保存用户的完整提示词和模型回答。

4. 用真实任务比较模型

不要只用“你好”判断模型质量。准备一小组来自真实业务的固定样本，比较正确率、输出格式、延迟和费用，再决定默认模型与备用模型。

七、常见配置问题

Base URL 后面要不要再加 /chat/completions？

使用 OpenAI Python SDK 时，base_url 填 https://api.siliconflow.cn/v1 即可，SDK 会拼接具体接口路径。直接发送 HTTP 请求时，完整地址才是 https://api.siliconflow.cn/v1/chat/completions。

为什么别人能用的模型，我这里提示不存在？

模型可能已经调整，也可能不在当前账号的可用范围。应通过当前账号查询 /v1/models，不要照抄旧教程中的模型 ID。

能不能把 API Key 写在前端 JavaScript 里？

不应该。浏览器会把代码和网络请求暴露给访问者。前端应用应调用自己的后端，再由后端读取环境变量并请求硅基流动。

OpenAI SDK 的所有功能都能直接使用吗？

不能这样假设。官方表述是部分大语言模型支持 OpenAI SDK，并支持其中的大多数参数。具体模型、接口和参数应以硅基流动当前文档为准。

请求成功但正文为空是什么原因？

先检查 finish_reason 和 reasoning_content。本文实测中，思考模型在较小的 max_tokens 下先耗尽了输出额度，导致正文为空。可以关闭思考模式，或者提高输出上限并正确处理思考内容。

最后检查清单

• API Key 只从环境变量读取；
• Base URL 使用 https://api.siliconflow.cn/v1；
• 模型 ID 来自当前账号的模型列表；
• 最小调用能返回内容、模型名和 Token 用量；
• 程序设置了超时和有限重试；
• 日志不包含 API Key；
• 上线前用真实业务样本比较质量、延迟和成本。

如果这七项都已确认，硅基流动的基础 API 接入就算完成。下一步不是继续堆参数，而是用自己的真实任务选模型，并建立费用和失败率监控。

官方资料

• 快速上手
• 获取用户模型列表
• 创建对话请求（OpenAI）
• API 错误处理
• Rate Limits
• 模型价格中心

信息核验时间：2026 年 8 月 29 日。接口、模型、价格和限速可能调整，请以硅基流动官方文档、模型列表和价格中心为准。真实调用结果只代表上述时间、账号和测试模型，不代表其他模型或未来状态。