Embedding API Key 获取教程：注册、创建与安全配置（2026）

Embedding API 的 Key 和聊天模型的 Key 在多数平台上没有区别：它只是身份凭证，真正决定你能调什么的是账号权限和请求里的模型参数。但向量化任务往往跑在后台、批量处理大量文档，Key 一旦泄露或配错，损失和排查成本都不低。

本文按顺序讲清楚：在哪里注册、创建 Key 时填什么、权限怎么分、环境变量怎么放、401 怎么查、官方 Key 和网关 Key 怎么选，以及轮换和泄露处理。

说明：OpenAI 及其他文中提及的品牌均为其权利人的商标。本文仅用于技术说明，与相关厂商无隶属关系；接口、权限和价格以各平台官方文档及站内页面为准。

一、先确认：Embedding 需要单独的 Key 吗

多数 OpenAI 兼容平台用同一套鉴权：同一个 Key 既能调 /v1/chat/completions，也能调 /v1/embeddings。是否可用取决于账号余额、模型权限和平台策略，而不是 Key 的类型。

少数平台会把向量服务单独计费或单独授权。创建前先在控制台确认三件事：

当前套餐或余额是否覆盖 embedding 模型。
Key 是否有模型白名单或项目范围限制。
embedding 与聊天是否共用额度。

如果控制台没有细粒度权限选项，就按“一个用途一把 Key”来隔离，至少能做到限额和单独停用。

二、注册与进入控制台

以中商起航 AI 网关为例：

打开 https://ai.zhongshangqihang.com，用邮箱注册并完成验证。
登录后进入控制台，找到「API 密钥」页面。
在「钱包」或「充值」页面确认余额，测试阶段先充小额即可。
打开「用量日志」，确认能看到模型、Token 和费用记录。

注册入口也可以直接用注册链接。如果你只想先验证接口，不急着充值，先创建一把低额度测试 Key，跑通后再调整。

三、创建 Key 时怎么填

点击「新建密钥」，通常会看到以下字段：

名称：写清用途和环境，例如 rag-prod-backend、embedding-batch-dev。不要用“测试1”这种名字。
额度上限：先设低一些，确认批量任务的真实消耗后再提高。
过期时间：临时脚本设 7 天或 30 天；生产 Key 也要有固定轮换周期。
模型或项目范围：如果平台支持，只勾选 embedding 模型和必要项目。
保存并复制：完整 Key 通常只显示一次，没保存就只能删除重建。

Key 一般以 sk- 开头，但前缀不是判断真伪的依据。复制时注意不要带上首尾空格或换行，这是 401 的常见原因之一。

四、权限与额度怎么设计

向量化任务的特点是“读多写少、批量跑、容易重试”。权限设计的目标不是防外部攻击，而是防止一把 Key 影响所有环境。

场景	Key 命名	额度	存放位置	轮换
本地开发	`emb-dev-姓名`	最低档	本机 `.env`	30 天
测试环境	`emb-staging`	低	CI/CD 密钥	60 天
生产批量	`emb-prod-batch`	按预算	密钥管理服务	90 天
生产查询	`emb-prod-query`	按预算	密钥管理服务	90 天

几个原则：

开发和生产分开：测试 Key 泄露不会影响生产账单。
批量和查询分开：批量任务容易重试，单独限额便于定位异常消耗。
最小权限：能只开 embedding 就不开聊天模型；能限制项目就不给账号级权限。
不放进前端：浏览器、App 和小程序里的 Key 一定会被提取，向量化请求必须走自己的后端。
不共用个人 Key：同事离职或设备丢失时，共用 Key 无法单独停用。

五、把 Key 放进环境变量

不要硬编码在代码里。Python 项目可以这样读取：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["第一段文本", "第二段文本"],
)
print(len(resp.data[0].embedding))

本地用 .env 时，把文件加入 .gitignore，只提交 .env.example。生产环境优先使用容器 Secret、云厂商密钥管理或 Vault 一类服务，不要把 Key 写进 Dockerfile、镜像层、前端打包产物或 CI 日志。

还要注意：改了环境变量后要重启进程。很多“线上 401、本地正常”的问题，原因是服务读到的还是旧变量，或者部署平台没有把变量注入到运行环境。

六、401 排查顺序

遇到 401 Unauthorized，按这个顺序查，通常几分钟能定位：

检查请求头是否是 Authorization: Bearer sk-...，Bearer 和 Key 之间是一个空格。
重新复制 Key，确认没有空格、换行、引号或不可见字符。
确认 Key 没有被删除、禁用或过期。
确认 Key 属于当前 Base URL 对应的平台，不要把 A 平台的 Key 发到 B 平台。
确认进程实际读到了环境变量，而不是空字符串。
检查反向代理、网关或 SDK 是否改写了 Authorization 头。
如果只有部分请求失败，检查是否有人在前端代码里暴露了 Key 后被风控停用。

补充一句：401 是身份问题，403 多是权限或地区限制，429 多是频率或额度问题。不要把失败都归因于 Key。

七、官方 Key 还是网关 Key

两条路都能用，差别主要在采购、网络和维护：

官方直连：账号、账单和模型都由原厂管理，适合有海外支付能力、能自己处理网络和合规的团队。缺点是模型分散在多家平台，Key 和对账也要分开管理。
网关接入：一个 Base URL、一把 Key 调多家模型，国内访问和人民币结算更省事，日志和限额也集中。代价是多了一层依赖，需要确认服务商的数据政策、可用性和故障处理方式。

选择时不要只看价格。至少确认：数据是否会被留存、是否支持发票、故障时怎么通知、模型下线有没有提前公告、能否导出用量记录。具体模型和价格以模型价格当前展示为准，价格会调整，不要按旧文章的数字做预算。

八、轮换与泄露处理

建议把轮换做成固定动作，而不是出事才做：

在原平台创建一把同权限的新 Key。
更新环境变量或密钥管理中的值。
重启或重新部署服务，调用一次 embedding 接口确认成功。
观察 24 到 48 小时用量日志，确认没有异常。
删除旧 Key，并记录轮换时间。

怀疑泄露时，顺序要反过来：先停用旧 Key，再排查用量日志和代码仓库历史，最后才创建新 Key。只删代码里的字符串不够，Key 可能已经进入 CI 日志、镜像层或第三方缓存。

常见问题

Embedding 一定要单独的 Key 吗？

不一定。多数 OpenAI 兼容平台允许同一把 Key 调用 embedding 和聊天接口。是否单独创建，取决于你是否需要分开限额、分开审计或单独停用。

Key 创建后还能看到完整内容吗？

通常不能。完整 Key 只在创建时显示一次，之后只保留前缀或掩码。没保存就删除重建，不要试图从日志里找回。

一个 Key 能调用多个 embedding 模型吗？

通常可以，模型在请求的 model 字段里指定。具体可用模型和维度以平台文档及模型价格为准。

本地 curl 成功，线上却返回 401，为什么？

优先查三件事：线上环境变量是否注入、反向代理是否保留 Authorization 头、线上是否用了另一把已删除或过期的 Key。其次再查 Base URL 是否指向了错误的平台。

Key 泄露后删掉就够了吗？

不够。先停用 Key，再查用量日志确认是否有异常调用，检查代码仓库、CI 日志和镜像历史，最后轮换所有可能受影响的 Key。如果 Key 有充值余额，还要评估是否需要调整额度。

下一步

如果还没有账号，可以从注册页开始，创建一把低额度 Key，先用一条文本跑通 /v1/embeddings。跑通后再看模型价格选择正式模型。向量化流程本身，可以继续读下面的接入教程。