FACE API 提示 invalid subscription key，如何解决？

2026-10-24支付阿杰

结论

subscription key 不是通用凭据。Face API 的 key 必须与创建它的 Azure 资源、API 类型和区域端点一致。无论使用免费试用 key 还是“Pay as you go”key，只要调用了错误的区域或服务端点，或者 key 属于其他 API，都会返回：

Access denied due to invalid subscription key.

因此，不能只替换 key。请从同一个 Face 或 Azure AI services 资源中复制 Key 和 Endpoint，并将两者一起传给客户端。

为什么多个 key 都会失败

示例代码只传入了 key：

new FaceServiceClient("39a8b...0fd1");

某些旧版 Face SDK 在没有指定服务地址时，会使用默认 API 地址。这个地址不一定与 key 所属的区域一致。例如，为 westus 资源生成的 key，通常不能直接用于另一区域的 Face API 端点。

其他可能的原因包括：

key 属于 Computer Vision、Search 等其他 API，不属于 Face API；
key 来自一个 Azure 资源，程序调用的却是另一个资源的 endpoint；
key 已被停用、删除或重新生成；
复制 key 时带入了空格、换行或引号；
教程使用旧版 SDK，其默认 endpoint 不适用于当前创建的资源；
当前订阅或资源没有 Face API 的使用权限。某些时期和区域可能对 Face 服务设置访问资格限制，具体以 Azure 门户显示的资源状态为准。

计费方式不会直接决定 key 是否有效。免费试用和按量付费凭据都必须满足相同的资源与 endpoint 匹配要求。

如何确认订阅了正确的 API

资源类型应为 Face，或者是明确支持 Face 能力的 Azure AI services 多服务资源。
打开资源的 Keys and Endpoint 页面。
从该页面复制 KEY 1 或 KEY 2。
同时复制页面显示的 Endpoint。
确认程序中的 key 和 endpoint 来自同一个资源，不要混用不同资源的信息。
检查资源是否已启用、订阅是否有效，并确认资源所在区域支持当前调用的 Face API。

如果门户中只有 Computer Vision 等其他服务的资源，其 key 不能直接用作独立 Face 资源的 key，除非该资源类型和当前服务配置明确支持 Face API。

为 `FaceServiceClient` 指定正确的 endpoint

使用旧版 Microsoft.ProjectOxford.Face SDK 时，应显式传入 API 根地址，不要依赖默认值：

private readonly IFaceServiceClient faceServiceClient =
    new FaceServiceClient(
        Environment.GetEnvironmentVariable("FACE_API_KEY"),
        "https://westus.api.cognitive.microsoft.com/face/v1.0"
    );

var faces = await faceServiceClient.DetectAsync(imageFileStream);

这里的 westus 只是示例，必须将整个地址替换为资源对应的 Face API 地址。

某些 Azure 资源使用资源专属 endpoint，例如：

https://your-resource-name.cognitiveservices.azure.com/

旧版 FaceServiceClient 可能要求传入包含 /face/v1.0 的 API 根路径：

private readonly IFaceServiceClient faceServiceClient =
    new FaceServiceClient(
        Environment.GetEnvironmentVariable("FACE_API_KEY"),
        "https://your-resource-name.cognitiveservices.azure.com/face/v1.0"
    );

是否需要追加 /face/v1.0，取决于所用 NuGet 包及其版本。在确认 SDK 的要求之前，不要混用新旧教程中的 endpoint 格式。

直接验证 key 与 endpoint

排查 SDK 问题时，可以绕过 SDK，直接发送 HTTP 请求。以下 endpoint 仅为示例：

curl -i \
  -H "Ocp-Apim-Subscription-Key: YOUR_FACE_API_KEY" \
  "https://westus.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true" \
  --data-binary "@photo.jpg" \
  -H "Content-Type: application/octet-stream"

如果直接请求仍然返回 401 或 invalid subscription key，问题通常不在 DetectAsync，而在以下方面：

key 与 endpoint 不属于同一个资源；
key 不属于 Face API；
endpoint 的区域不正确；
key 已失效；
资源或订阅不可用。

如果 HTTP 请求成功而 SDK 调用失败，请检查 SDK 版本、构造函数参数和 API 根路径格式。

建议的排查顺序

在 Azure 门户中打开目标 Face 资源。
从同一个 Keys and Endpoint 页面重新复制 key 和 endpoint。
在代码中显式设置 endpoint。
去除 key 前后的空格和换行。
使用 curl 或其他 HTTP 客户端验证请求。
如果仍然失败，重新生成资源的 key，并同步更新程序配置。
如果教程发布较早，检查其中使用的 NuGet 包是否已经弃用，并改用该资源当前文档对应的 SDK。

不要将真实 key 直接写进源代码或提交到版本库。请使用环境变量、用户机密或密钥管理服务保存：

string key = Environment.GetEnvironmentVariable("FACE_API_KEY")
    ?? throw new InvalidOperationException("FACE_API_KEY is not configured.");

归根结底，Face API 的 key、endpoint、区域和资源类型必须对应同一个 Azure 资源。只更换 key，却继续访问错误的 endpoint，无法解决这个错误。