GCP 300 美金赠金开通 Vertex AI / Gemini API 说明书

0. 先选路线

不要一上来就找“API Key”。先看你要接入的工具让你填什么。填错路线会出现 401、403、404，或者更麻烦：走到了 AI Studio 计费口。

推荐先试

工具支持 Vertex AI + API key

走路线 A。创建 Agent Platform API key，填密钥和 Vertex AI URL。适合支持自定义 URL 的聊天客户端、中转服务、开发测试。

最通用

工具要服务邮箱、私钥、项目 ID

走路线 B。下载服务账号 JSON，从里面取 `client_email`、`private_key`、`project_id`。

官方 SDK

工具要求 Google Cloud SDK / ADC

用 `gcloud init` 和 `gcloud auth application-default login`。这是 Google 官方更推荐的生产认证方式。

谨慎

工具只支持 AI Studio key

不要把这类 key 当成 Vertex AI。它通常指向 `generativelanguage.googleapis.com`，可能不走 GCP 免费试用赠金。

1. 入口地图

下面这些链接建议先收藏。Google 控制台菜单经常改名，用入口链接比靠侧边栏慢慢找可靠。

结算与赠金

Billing，再进 Credits / Reports 看余额和消耗。

模型列表

Agent Platform 模型，模型 ID 通常取 `gemini-*` 那段。

官方 API key 文档

Google Cloud：API keys for Vertex AI。

2. 项目与赠金

先确保你在正确项目和正确结算账号里操作。很多“配置失败”其实是项目选错、组织策略限制，或误把非赠金结算账号绑定到了项目。

确认你看到免费试用赠金

GCP 免费试用通常是 300 美元、90 天。Google 官方说明免费试用结束或赠金用完后，未升级账号不会继续自动收费，资源会停止。

GCP 免费试用赠金横幅截图 — 确认自己在带免费试用赠金的 Cloud Billing 账号下操作。

如果账号有组织，优先创建“无组织”项目

论坛教程建议无组织项目可以少碰组织策略。创建项目时，结算账号选带赠金的 My Billing Account，组织选择 No organization。

创建无组织项目 — 项目名称随意；结算账号选赠金账号；组织选 No organization。

不要把 AI Studio 当作赠金路线

如果你的入口是 Google AI Studio 的 Get API key，先停下。官方免费试用文档把 AI Studio 的 Gemini API 用量列为赠金不可抵扣的例外之一。这里不是说 AI Studio 不能用，而是说它不适合作为“消耗 GCP 300 美金赠金”的默认路线。

3. 一键启用 API

较新控制台把 Vertex AI 相关入口归到 Gemini Enterprise / Agent Platform。新教程里最省事的做法是从 Agent Platform 概览页一键启用所需 API。

打开 Agent Platform → 概览

入口：https://console.cloud.google.com/agent-platform/overview。也可以从侧边栏进 Agent Platform，再点 Overview / 概览。

Agent Platform 侧边栏入口 — 侧边栏：Agent Platform → 概览。

Agent Platform Enable APIs 按钮 — 看到 Enable APIs 后点击，等待一两分钟。

启用 API 后的身份验证界面 — 启用完成后，会进入身份验证 / 环境 / 调用模型的配置界面。

没有一键按钮时，直接启用 Vertex AI API

备用入口：启用 aiplatform.googleapis.com。启用后再回到 Agent Platform 概览或凭据页。

4. 路线 A：API key

适合工具明确支持 Vertex AI API key，或者支持“Google 提供商 + 自定义 URL”。这条路线最像你熟悉的一串密钥，但要注意 URL 必须是 Vertex AI 的 `aiplatform.googleapis.com`。

在身份验证弹窗里选择 API 密钥

点击 API 密钥右侧的“设置 / Set up”，再点 Create API Key。新教程经验是：创建出的 Agent Platform API key 通常以 `AQ.` 开头。

身份验证里选择 API 密钥 — 身份验证页：API 密钥这一行右侧点“设置”。

Create API Key 按钮 — 点击 Create API Key，创建后立即保存密钥。

把工具的 Base URL 改成 Vertex AI

论坛教程反复强调：Vertex AI API 不走 `generativelanguage.googleapis.com`。如果工具让你填自定义 URL，用下面格式。工具如果会自动拼 `v1beta`，要关掉或换工具，否则容易 404。

global 区域：
https://aiplatform.googleapis.com/v1/publishers/google

固定区域，例如 us-central1：
https://us-central1-aiplatform.googleapis.com/v1/publishers/google

不要写成：
https://generativelanguage.googleapis.com/...

不要在后面再加：
/v1beta

工具有 Vertex AI 提供商：优先选 Vertex AI，然后填 API key、区域和模型。
工具只有 Google 提供商但支持自定义 URL：填上面的 Vertex AI URL。
工具自动把 URL 改成 `.../v1beta`，且不能关闭：大概率不适合直连 Vertex AI。

最小配置模板

字段	填写	说明
API Key	Agent Platform 创建的一串密钥	不要填 AI Studio 的旧 Gemini key。
Base URL	`https://aiplatform.googleapis.com/v1/publishers/google`	global 区域；固定区域把开头改成 `{region}-aiplatform`。
模型	`gemini-2.5-flash` 或控制台里可见的 `gemini-*`	新模型、preview 模型优先试 global。
区域	`global` / `us-central1` / `us-west1` / `asia-east1`	区域错误会 404；429 多时可换区域或稍后再试。

5. 路线 B：服务账号 JSON

适合工具要求服务邮箱、私钥、项目 ID，或者环境变量 `GOOGLE_CREDENTIALS_JSON`。这条路线兼容老教程、hajimi 一类项目，也更接近 Google Cloud 的标准身份体系。

权限不要盲目给太大

旧教程常让服务账号使用 Vertex AI Administrator，这通常能跑，但权限偏大。Google 官方快速开始要求的是 Vertex AI User（`roles/aiplatform.user`）。个人测试可先用 Vertex AI User；确实需要管理资源时再临时加更高权限，完成后回收。

从一键流程生成的服务账号继续

新教程的一键流程会自动创建服务账号。进入 IAM 和管理 → 服务账号，点 `vertex-express` 开头的服务账号，再进入 Keys / 密钥。

vertex-express 服务账号 — 点击 `vertex-express` 开头的服务账号。

服务账号添加 JSON 密钥 — 上方切到 Keys，点击 Add key → Create new key。

选择 JSON 密钥类型 — 类型选择 JSON。文件只会下载一次，立刻保存好。

旧教程 / hajimi 的手动服务账号路线

如果没有自动创建服务账号，可以按旧教程搜索 Service Accounts，手动创建服务账号并授予 Vertex AI 权限。下面这些图来自 hajimi 的 Vertex AI 配置指南，和早期 GCP300 Vertex 教程的思路一致。

Google Cloud Console 首页 — 访问 Google Cloud Console。

选择 Vertex AI Administrator 权限 — 旧教程选 Vertex AI Administrator；更保守做法是先试 Vertex AI User。

从 JSON 里提取字段

如果工具让你上传整个 JSON，就直接上传或粘贴整个文件。若工具要分字段填，按下面对应关系。

{
  "type": "service_account",
  "project_id": "项目 ID",
  "private_key": "-----BEGIN PRIVATE KEY-----\n很长的私钥\n-----END PRIVATE KEY-----\n",
  "client_email": "服务账号邮箱@项目.iam.gserviceaccount.com"
}

工具字段	JSON 字段	注意
Project ID / 项目 ID	`project_id`	不是项目名称，是项目 ID。
Client Email / 服务邮箱	`client_email`	通常以 `.iam.gserviceaccount.com` 结尾。
Private Key / 私钥	`private_key`	保留 BEGIN/END 和换行；不要漏掉 `\n`。
Location / 区域	手动填	常用 `global` 或 `us-central1`。

6. 模型与区域

Vertex AI 的模型可用性和区域强相关。模型 ID、区域、Base URL 三者必须对上。

模型 ID 从哪里看

进入 Agent Platform → Models。点进模型详情后，取最后的 `gemini-*` 部分作为模型 ID。不要把完整资源路径整段复制进工具。

区域怎么选

新发布模型、preview 模型优先试 `global`。固定区域可试 `us-central1`、`us-west1`、`asia-east1` 等，具体以官方模型页和控制台为准。

Agent Platform 模型 ID 截图 — 模型页面里能看到模型资源名；配置工具时通常只取 `gemini-*`。

模型列表拉不出来，不一定是错

论坛教程提到：有些工具无法从 Vertex AI 拉取模型列表是正常现象，需要手动填模型 ID。判断配置是否成功，应该用一次真实请求，而不是只看列表能否加载。

7. 验证与排错

创建完成后不要马上大量并发。先做一次最小请求，再看费用、配额和错误码。

能用

一次简单对话返回正常

说明密钥、项目、区域、模型基本正确。下一步再接入你的客户端或中转。

404

多半是 URL 或区域错

检查是否错误拼了 `v1beta`；检查模型是否支持当前区域；preview 模型先换 `global`。

403

多半是权限或 API 未启用

检查 Vertex AI API 是否启用，服务账号是否有 Vertex AI User，项目是否绑到赠金结算账号。

429

共享动态配额拥挤

Google 官方文档说明 Pay-as-you-go 使用 Dynamic Shared Quota；429 可能是共享池高需求，建议重试、降并发、换区域或稍后再试。

余额与扣费自查

Billing 里确认当前结算账号仍是 Free trial account，而不是 Paid account。
从使用到结算报表更新可能有延迟，不要用一两分钟内的账单页面判断“完全没扣”。
不想转付费就不要点 Activate / Upgrade。免费试用用完后继续使用需要手动升级。
API key 或 JSON 泄露后，立即删除 key 或轮换服务账号密钥。

Billing 免费试用账号截图 — Billing 里看 Free trial account / Paid account 状态。

8. 来源与边界

这份说明书把论坛经验做成操作流，但事实口径优先按 Google 官方文档核对。论坛内容适合指路，官方文档适合判断计费、认证和权限。

关于 linux.do 原帖 566379

该链接在未登录公开抓取时返回“页面不存在或私密”。本说明书保留入口链接，并用同路线的 hajimi Vertex 配置指南截图补齐旧教程的服务账号 JSON 流程。若登录后能查看原帖，可把它作为旧路线参考，但权限和计费结论仍建议以 Google 官方文档为准。

linux.do 原帖：GCP300 / Vertex APIKEY 相关帖：当前公开抓取不可见，作为入口保留。
linux.do：如何使用 Google Cloud Platform 里的 Gemini (Vertex AI)：新教程截图与 Agent Platform 路线来源。
Google Cloud Free Program 文档：免费试用、赠金、AI Studio Gemini API 例外和升级规则。
Google Cloud：Vertex AI API keys：API key 与服务账号绑定说明。
Google Cloud：Vertex AI quickstart：新用户、已有项目、ADC/API key 认证要求。
Google Cloud：从 Google AI Studio 迁移到 Agent Platform：Gemini Developer API 与 Vertex AI / Agent Platform 的认证和计费差异。
Google Cloud：Throughput quota：Dynamic Shared Quota 与 429 解释。
hajimi：Vertex AI 配置指南：旧服务账号 JSON 路线截图来源。