maskanx_cm_backend/docs/GEMINI_VERTEX_SETUP_GUIDE.md

Setting up Gemini (Google) as a model provider

This covers Settings → Models → Gemini (Google) in MaskanX: both ways to connect it, every wall we actually hit setting it up the first time, and the exact click-path past each one. If you're configuring a new computer and something fails, search this document for the error message you're seeing — it's almost certainly here, worded exactly as Google shows it.

The one thing to understand before anything else

Nothing about this setup travels with git pull. Not the API key, not the Google Cloud Project ID, not a gcloud login, not a service account file. All of it lives only on the computer where you entered it. Two machines running identical MaskanX code can behave completely differently because one of them was never individually configured — that isn't a bug, it's how credentials are supposed to work (the alternative is secrets sitting in git, which is worse). Every computer that runs MaskanX needs this setup done on it, once, by itself.

---

Which of the two ways do you need?

	Plain API key	Google Cloud Vertex AI
Good for	Just using Gemini, nothing else	Billing through Google Cloud, enterprise setups, Gemini image generation
Setup effort	One box, one paste	Several steps, described below
Where the key comes from	aistudio.google.com	A Google Cloud Project

If you just want Gemini working and don't care about Google Cloud billing: get a key from Google AI Studio, paste it into the API Key box in the Configure Gemini dialog, leave "Use Vertex AI billing" switched off, and you're done. Skip the rest of this document.

If you need Vertex AI (the switch is on), keep reading — this is the path with all the gotchas.

---

Part 1 — Vertex AI setup

1.1 Find your Google Cloud Project ID

Go to console.cloud.google.com. Click the project name at the top-left. The ID shown under the display name (not the display name itself — a project's name and ID are different things, and the name is often the unhelpful default "My First Project") is what goes in the Google Cloud Project ID field. It looks like project-b6a838f4-89bb-48f7-841 or a custom slug you chose yourself.

1.2 Vertex Location

Use global unless you specifically know your model needs a particular region.

1.3 Authenticate — pick ONE of these two methods

Method A — Local login (recommended for a laptop / local dev)

No file to handle, nothing to paste. In a terminal on that specific computer:

gcloud auth application-default login

• If the terminal says gcloud is not recognized, the Google Cloud CLI isn't installed yet: cloud.google.com/sdk/docs/install, run the installer, then open a new terminal window before retrying (the old one won't know the tool exists).
• A browser window opens. Sign in with the Google account that owns/has access to the Cloud project. Click Allow.
• The terminal prints Credentials saved to file: ... — that's success.
• Leave the Service Account JSON box in MaskanX completely empty.

This is per-machine. Doing this on one laptop does nothing for another.

Method B — Service Account JSON (for a deployed server, or if gcloud isn't available)

A service account is a robot identity, not your personal Google login. You never hand-type this file — you download it complete from Google Cloud Console.

1. console.cloud.google.com/iam-admin/serviceaccounts — confirm the correct project is selected at the top first.
2. Use an existing service account if one already exists for this purpose, or + CREATE SERVICE ACCOUNT → give it any name → Create and Continue → under "Grant this service account access," add the role Vertex AI User → Continue → Done.
3. Click into that service account → KEYS tab → ADD KEY → Create new key → JSON → CREATE. A file downloads automatically.
4. Open the downloaded file in Notepad, select all, copy.
5. Paste the entire file contents, unedited, into the Service Account JSON box in MaskanX.

A real service account key has about ten fields, including a private_key block starting with -----BEGIN PRIVATE KEY-----. If what you're pasting doesn't look like that, it isn't a real key — see the troubleshooting table below.

Keep this file private. Anyone who has it can act as that service account in your Cloud project. Don't post it, don't commit it to git. Once it's pasted into MaskanX it's safe to delete the downloaded copy.

1.4 Grant the service account permission (Method B only)

Even with a valid key, Google will refuse every request until the account is allowed to use Vertex AI:

1. console.cloud.google.com/iam-admin/iam
2. + GRANT ACCESS → paste the service account's email (looks like name@project-number.iam.gserviceaccount.com) → role Vertex AI User → Save.
3. Changes can take a minute or two to take effect. If it still fails immediately after granting, wait and retry before assuming it's wrong.

1.5 Make sure the Vertex AI API is turned on

console.cloud.google.com/apis/library/aiplatform.googleapis.com — confirm the right project is selected, click Enable if it isn't already on.

---

Part 2 — If Google blocks key creation entirely

Some Google Cloud organizations have a security default that stops anyone from creating a service account key, before you even get to pick which service account. If Method B gives you this instead of a download:

Service account key creation is disabled An organisation policy that blocks service accounts key creation has been enforced on your organisation.

This is two separate locks, not one — Google runs an old version and a new "managed" version of this policy at the same time, and disabling one does not disable the other. Both must be turned off individually if you need Method B (Method A is unaffected by this entirely, which is one more reason to prefer it).

1. ☰ menu → IAM & Admin → Organization policies.
2. Filter box on that page (not the global search bar at the top of the whole console) → type service account key.
3. Two rows will match: "Disable service account key creation" with constraint ID iam.disableServiceAccountKeyCreation (labeled "Managed (legacy)"), and another with the same display name and ID iam.managed.disableServiceAccountKeyCreation (labeled "Managed"). You need to fix both, separately.
4. Click into one → Manage policy → select "Override parent's policy" → under Rules, select Enforcement "Off" → click Done to close that box.
5. Then scroll to the very bottom of the page and click "Set policy." Clicking "Done" alone does not save anything — it only closes the rule editor. This exact step is the one everyone misses, twice.
6. Confirm the page now shows Status: Not enforced.
7. Repeat steps 4–6 for the other row (if you're on one, the other one's page usually has a banner offering to jump straight to it).
8. Only once both show "Not enforced," go back and try creating the key again (Part 1.3, Method B, step 3).

You need the Organization Policy Administrator role to do this. If the "Override parent's policy" option isn't available to click, someone else administers your organization and needs to either do this for you or grant you that role.

---

Troubleshooting — exact error message → real cause → fix

You see	What's actually happening	Fix
Gemini (Google) model does not exist or is not available	Either the newest model genuinely isn't rolled out to this Cloud project yet (MaskanX automatically tries older ones and should recover on its own), or something else is failing and getting mis-read as this. Check the backend terminal for a line starting Gemini/Vertex request failed or Gemini/Vertex probe: — it logs Google's real, unfiltered error there.	Read the real error in the terminal, then find it in this table.
Your default credentials were not found	This computer has never authenticated to Google Cloud. This is not about the API key, the Project ID, or which model was picked — it fires identically no matter what else is configured correctly.	Part 1.3, Method A (or B).
Service account key creation is disabled	An organization policy is blocking it — see Part 2.	Part 2.
Service account info was not in the expected format, missing fields client_email, token_uri	What was pasted into the Service Account JSON box isn't a real, complete key file — often someone's email and project ID typed in by hand instead.	Download the real file (Part 1.3, Method B) and paste the whole thing, unedited.
API key was accepted, but this Google project does not have permission for the requested Gemini API/model	Authentication succeeded, but the account isn't allowed to use Vertex AI yet.	Part 1.4 — grant the Vertex AI User role.
API key is invalid or expired	The key itself (plain API key, or the token behind Vertex auth) is wrong or has been revoked.	Re-check/regenerate the key.
currently rate-limited or out of quota	Real usage limit hit.	Check quota/billing in Cloud Console, or wait.
billing is required for this Gemini request	The Cloud project has no billing account attached.	console.cloud.google.com/billing — attach one.

---

Quick reference

Thing	Where to find it
Project ID	Cloud Console → project switcher, top-left → the ID under the display name
Service account email	IAM & Admin → Service accounts → the "Email" column
Grant a role	IAM & Admin → IAM → "+ Grant Access"
Turn on the Vertex AI API	APIs & Services → Library → search "Vertex AI API"
Org policy list	IAM & Admin → Organization policies

If none of this matches what you're seeing, the backend terminal log is the next place to look — every Gemini/Vertex failure now logs the exact, unedited text Google sent back, not just a paraphrase.