主题
3.2 API Key：申请、计费与密钥管理
给办公室设备办一张使用卡，后台就能识别使用者并记录费用。API Key 有类似作用：程序向服务端发出请求时携带密钥，服务端据此进行认证，并按账户、项目与权限规则处理请求。
它不是模型本身，也不等于网页聊天会员。一个账户可以拥有多把密钥，一把密钥的可用范围则取决于服务商和项目设置。把这几件事区分开，后续配置就会清楚得多。
发起一次请求，需要哪些信息
通常需要确认四项：服务地址、认证方式、模型标识和请求格式。它们像营业地址、使用卡、服务项目和申请表，缺一项或搭配错误都可能失败。
| 配置 | 含义 | 常见错误 |
|---|---|---|
| Base URL | 请求发往哪个服务入口 | 把官网首页当成 API 地址 |
| API Key | 服务如何识别调用者 | 用另一家平台的密钥 |
| Model ID | 调用哪个可用模型 | 复制宣传名称，未使用接口标识 |
| API 格式 | 请求与响应怎样组织 | 把不同接口的参数混用 |
确认这些信息时，优先查看平台控制台与官方接入示例。“兼容某种 API”不代表所有功能都兼容，还需要检查流式输出、工具调用和图片输入等实际需求。
怎样申请一把用于练习的密钥
可以从已经能正常访问的平台开始，不必为了入门同时开通多个账户。以下是常见入口，不按能力或价格排名：
一般流程是注册账户、确认服务可用范围、建立项目、创建密钥，再设置可用额度。付款方式、试用额度和模型权限可能变化，应按所选平台的当前说明操作。
给密钥取一个能认出用途的名称，例如“笔记项目本地测试”。如果平台支持，开发与正式环境分别创建密钥，便于单独撤销和查看用量。完整密钥只展示一次时，应保存到密码管理器或受控的本地配置中，避免散落在聊天、截图与普通笔记里。
Token 计费怎样理解
Token 是模型处理文本时使用的片段，可能是一个字、半个词、完整词语或其他组合，不能固定按“一个汉字等于一个 Token”计算。具体切分由模型的分词器决定。
账单可能区分输入、缓存输入与输出，还可能包含工具、图片、音频或其他费用。模型计费应以实际接口用量和对应价格表为准。可参考 DeepSeek Token 用量说明与价格页。
用一组假设价格练习计算
以下数字仅用于演算，不代表任何平台当前售价。假设普通输入每百万 Token 为 2 元，缓存输入为 0.5 元，输出为 8 元。
| 本次用量 | 计算 | 费用 |
|---|---|---|
| 普通输入 2,000 Token | 2,000 ÷ 1,000,000 × 2 | 0.004 元 |
| 缓存输入 8,000 Token | 8,000 ÷ 1,000,000 × 0.5 | 0.004 元 |
| 输出 1,000 Token | 1,000 ÷ 1,000,000 × 8 | 0.008 元 |
| 合计 | 三项相加 | 0.016 元 |
这个例子中输入总量为 10,000 Token，缓存部分是其中的 8,000，不能再按普通输入重复计费。实际平台的用量字段含义需要单独核对。
智能体一次任务往往发起多轮调用，后续请求还可能包含已有对话和工具结果。因此“问了一句话”并不等于“只有一次请求”。核算费用时，应汇总整个任务，而不是只看最后一条回答。
网页订阅、编程套餐与按量 API
| 方式 | 通常购买的是什么 | 开通前要确认 |
|---|---|---|
| 网页或应用订阅 | 指定产品内的使用权益 | 是否包含所需工具与模型 |
| 编程套餐 | 指定工具或接口的编程额度 | 支持哪些客户端、怎样限额 |
| 按量 API | 程序调用服务的用量 | 价格、速率、预算与超额规则 |
有些套餐可以用于特定编码工具，但未必允许拿来运行面向用户的后台服务；网页会员也不应默认视作通用 API 余额。即使套餐额度固定，泄露密钥仍可能暴露数据或让额度被他人耗尽。
如果用量尚不明确，可以先完成一两个小任务，记录消耗和等待时间，再决定是否长期订阅。预算提醒不一定等于硬性停用，应核对平台是否真的会在达到上限后停止请求。
用环境变量读取密钥
环境变量像交给运行程序的一份本地配置，不需要写进源代码。练习项目可以借助 python-dotenv加载 .env，但 .env 是普通文本文件，不是加密保险箱。
1. 安装依赖
在项目虚拟环境中执行：
bash
python -m pip install python-dotenv2. 准备本地配置
创建 .env，填入自己平台的密钥。下面只有占位内容：
dotenv
MODEL_API_KEY=replace-with-your-key创建 .env.example 供其他人了解需要哪些变量，其中不放真实密钥：
dotenv
MODEL_API_KEY=在 .gitignore 中加入：
gitignore
.env
.env.*
!.env.example
.venv/这些规则只阻止未跟踪文件进入版本管理。已经被提交的文件不会因此自动退出跟踪，更不会从历史中消失。
3. 检查是否成功加载
python
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("MODEL_API_KEY")
if not api_key or api_key == "replace-with-your-key":
raise RuntimeError("请在本地配置中填写 MODEL_API_KEY")
print("已读取模型密钥")这段程序只检查配置是否存在，不会向模型发请求，也不能证明密钥有效。下一步再按照平台官方的最小示例发出一次短请求，并去控制台确认请求记录。检查时不必打印完整密钥。
调用失败时，从哪里查起
| 现象 | 优先检查 |
|---|---|
| 读取不到变量 | 文件位置、变量名和进程是否继承配置 |
| 401 | 密钥是否属于当前服务，是否失效或缺少认证信息 |
| 403 | 账户、项目或模型权限 |
| 404 | 接口路径与模型标识是否正确 |
| 429 | 速率限制、额度或并发限制，以及服务返回说明 |
| 超时 | 网络、服务状态、输入长度和超时设置 |
不要为了排错把密钥发到公开讨论区。需要他人协助时，提供去除敏感内容后的错误、请求地址结构和配置变量名称即可。
如果密钥已经泄露
先在平台撤销或轮换，再检查用量和访问记录，随后更新受影响的程序。只删除本地文件或最新提交，不能让已经被复制的密钥失效。
前端代码最终会交给浏览器执行，不能存放服务端密钥。需要调用付费模型时，通常由后端读取密钥并处理请求，再把允许展示的结果返回页面。
不同环境应使用不同密钥
本地开发、自动化测试和正式服务最好不要共用同一把密钥。分开之后，可以为每个环境设置不同额度和权限；某个测试密钥泄露时，也不必同时中断正式服务。
| 环境 | 建议权限 | 管理方式 |
|---|---|---|
| 本地练习 | 低额度、仅开放所需模型 | 本地环境变量或系统密钥库 |
| 持续集成 | 仅用于自动测试 | 仓库平台的加密 Secrets |
| 测试服务 | 独立项目与用量上限 | 部署平台的密钥管理功能 |
| 正式服务 | 最小权限、审计和定期轮换 | 专门的密钥管理服务 |
不要把正式密钥复制到截图、问题单或聊天记录中。演示配置时使用明显的占位符，并确认日志不会把请求头完整打印出来。
密钥轮换不是简单地改一行配置
轮换通常包含四步：创建新密钥、让服务加载新密钥、验证流量已经切换、撤销旧密钥。若先撤销再部署，服务会短暂中断；若创建后一直不撤销，旧密钥仍可被使用。
团队可以为密钥记录负责人、用途、创建日期和下一次检查日期。是否定期轮换要结合平台能力与风险要求，但人员离职、权限改变或疑似泄露时应立即处理。
自动检查只能作为最后一道提醒
提交前可以使用仓库平台的 Secret Scanning，或在本地加入密钥模式扫描。但扫描规则可能漏掉新格式，也可能把普通字符串误判成密钥。真正可靠的顺序仍然是：密钥不写入源码，配置文件加入忽略规则，提交前检查差异，平台侧设置最小权限和额度。
如果扫描工具报告问题，应先判断字符串是否真实凭据；一旦确认泄露，先撤销密钥，再清理仓库历史。只把当前文件中的字符替换掉，并不能消除已经推送到远端的副本。