调用Google Generative Language API遇ACCESS_TOKEN_SCOPE_INSUFFICIENT错误求助

背景 #

项目需用embedding-001模型实现文本嵌入功能，调用API时持续返回403权限错误，具体响应如下：

{
  "error": {
    "code": 403,
    "message": "Request had insufficient authentication scopes.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCESS_TOKEN_SCOPE_INSUFFICIENT",
        "domain": "googleapis.com",
        "metadata": {
          "method": "google.ai.generativelanguage.v1beta.GenerativeService.BatchEmbedContents",
          "service": "generativelanguage.googleapis.com"
        }
      }
    ]
  }
}

已完成的操作：

• 服务账号已配置对应角色（截图已验证）
• 生成服务账号密钥，指定API作用域：scopes = ["https://www.googleapis.com/auth/generative-language"]
• 使用以下代码完成认证（访问令牌已正常生成）：

  credentials = service_account.Credentials.from_service_account_file(
      service_account_key_path, scopes=scopes
  )
  credentials.refresh(Request())
  

但API调用始终报ACCESS_TOKEN_SCOPE_INSUFFICIENT错误，多次验证服务账号及作用域均无效。

针对问题的解决方案 #

1. 是否遗漏权限/作用域？ #

• 确认角色与作用域匹配：
  服务账号必须被授予Generative Language Developer角色（该角色包含调用BatchEmbedContents接口的权限），如果截图中的角色是 Viewer 或其他非开发类角色，会直接导致权限不足。
• 验证访问令牌的实际作用域：
  把生成的访问令牌放到这个接口查询：https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=你的令牌，查看返回的scope字段是否包含https://www.googleapis.com/auth/generative-language。如果没有，说明代码中指定的scopes未被正确应用——检查是否有环境变量（比如GOOGLE_APPLICATION_CREDENTIALS）的默认认证链覆盖了代码配置，或者尝试直接用密钥文件路径初始化客户端时强制指定scopes。
• 检查API是否启用：
  确保Google Cloud项目中已启用Generative Language API（控制台API库搜索启用），API未启用也会触发权限类错误。

2. embedding-001模型是否需要额外配置？ #

使用embedding-001不需要额外配置，但要注意两点：

• 调用接口时必须指定正确的模型名称：models/embedding-001，避免拼写或格式错误；
• 确认项目未超出模型调用配额：如果配额不足会报配额错误，而非权限错误，所以当前问题大概率和配额无关。

内容的提问来源于stack exchange，提问作者Siddhant Sancheti