Documentation
Gemini API Key Setup
Connect your own Google Gemini API key to use Cartographer's free BYOK tier.
Why a Paid Key?
Cartographer's free tier uses BYOK (Bring Your Own Key) — you supply a Google Gemini API key and map generation runs against your account directly. This keeps Cartographer's free tier sustainable while giving you full control over your usage.
Google offers a free Gemini API tier, but it enforces strict rate limits (15 requests per minute) that make it unreliable for map generation — a single stylization job can take multiple API calls. A Pay As You Go (paid) key removes these limits and ensures generations complete reliably.
You only pay for what you generate — there is no monthly minimum or standing charge on a Pay As You Go key.
Step 1 — Get Your API Key
- 1. Go to aistudio.google.com and sign in with your Google account.
- 2. In the left sidebar, click Get API key.
- 3. Click Create API key. When prompted, select an existing Google Cloud project or create a new one. The project name doesn't matter — it's just a container for billing.
- 4. Copy the generated key and store it somewhere safe. You will not be able to view the full key again after leaving this screen — but you can always revoke it and create a new one.
Keep your key private. Do not share it, commit it to version control, or paste it into public forums. Anyone with your key can run generations billed to your account.
Step 2 — Enable Pay As You Go Billing
Without billing enabled, your key operates on the free tier with rate limits. Follow these steps to upgrade it to Pay As You Go.
- 1. Go to console.cloud.google.com.
- 2. Use the project picker at the top of the page to select the same project you used when creating your API key in Step 1.
- 3. In the left navigation menu, go to Billing.
- 4. If billing is not yet linked, click Link a billing account. If you have an existing Google billing account, select it. Otherwise, click Create billing account and add a credit card.
- 5. Once the billing account is linked, your project — and therefore your API key — is now on the Pay As You Go plan. Rate limits are lifted immediately.
Tip: Google offers a $300 free credit to new Google Cloud accounts. If you have never used Google Cloud before, you may be able to run a large number of map generations before spending anything.
Step 3 — Add Your Key to Cartographer
- 1. Sign in at app.cartographer.live.
- 2. Open Settings from the top navigation, then select API Key.
- 3. Paste your Gemini API key into the field and click Save. Cartographer sends a quick validation request to confirm the key is working before storing it.
- 4. Once saved, all map generation on your account will use your key. The platform API key is not used for BYOK accounts.
Frequently Asked Questions
- Can I use the free Gemini API tier instead?
- You can try it, but the free tier's rate limits (15 requests per minute) frequently cause generation jobs to fail or time out. A Pay As You Go key is strongly recommended for a reliable experience.
- Will I be charged if I'm not generating maps?
- No. The Gemini API is billed purely on usage — there is no monthly minimum or standing charge. If you generate nothing, you pay nothing.
- Cartographer says my key is invalid — what do I check?
- First, confirm you copied the full key without trailing spaces. Then verify that billing is enabled on the associated Google Cloud project — a free-tier key will be rejected by Cartographer. Finally, make sure the Generative Language API is enabled in your project's API Library.
- Is my API key stored securely?
- Yes. Your key is encrypted at rest and is never exposed in API responses or logs. You can revoke and replace it at any time from Settings → API Key.
- Can I switch to a Pro subscription later and stop using BYOK?
- Yes. Pro subscribers use Cartographer's platform API key — you do not need to maintain your own. If you upgrade, your BYOK key is retained in settings but no longer used for generation.