Gemini API Tester

Read this before you paste a live API key

We would rather lose a click than be vague about this, so here it is in plain terms:

One Gemini-specific wrinkle worth knowing: if you restrict a key by HTTP referrer, it is designed to be called from a browser page on an allowed domain — and our request does not originate from your browser, it originates from our server. Such a key will be rejected here even though it is perfectly valid in its intended context. Keys restricted by IP address will likewise fail unless our egress address is allowed, which it will not be. That is not a bug in the key.

If none of this sits right for a particular credential, build the request here with the key field empty, press Copy as cURL, and paste the key in on your own machine. You get the exact request; the secret never leaves your laptop.

How to test a Gemini API key

1. Create a key

Gemini API keys are issued from Google AI Studio once you sign in with a Google account. Each key belongs to a Google Cloud project, which matters more than it first appears: several failure modes on this API are really project configuration problems wearing a key-shaped disguise. Copy the key somewhere safe when it is created.

2. Use the models endpoint as your probe

The request pre-filled above is a GET to https://generativelanguage.googleapis.com/v1beta/models. It requires authentication, generates no content, and returns the list of models the key can address — which doubles as a check that you are naming a model correctly in later calls. It is the ideal smoke test.

3. Send the key as a header

The Auth tab is already set to API key header with the header name x-goog-api-key filled in; paste the key into the value field beside it. The API also accepts the key as a key query parameter, and you will see that form in a great many tutorials, but you should avoid it. Query strings end up in server access logs, proxy logs, browser history and sometimes referrer headers — a header does not. Treat the query-parameter form as a convenience for throwaway experiments and the header as the way you actually ship. The HTTP headers guide covers why custom auth headers are handled differently from URLs all the way down the stack.

4. Send and read the response

A 200 with a JSON object containing a models array means the key is valid and the API is enabled for its project. Anything else needs interpreting, and Gemini's errors are less obvious than most.

Valid key vs invalid key: what you'll see

Success returns a JSON object whose models field is an array, each entry describing a model along with the operations it supports. The model name values are the strings you later place in a generation URL, so it is worth glancing at them rather than trusting a name you copied from a blog post.

Failure returns Google's standard error envelope: a top-level error object holding a numeric code, a human-readable message, and a status string such as INVALID_ARGUMENT or PERMISSION_DENIED. The status string is the field to read. It is far more precise than the HTTP status code and consistent across Google APIs.

GET https://generativelanguage.googleapis.com/v1beta/models
x-goog-api-key: <your key>

200 OK  → { "models": [ { "name": "models/…", … }, … ] }
error   → { "error": { "code": …, "message": "…", "status": "…" } }

Why a bad Gemini key gives you 400, not 401

This trips up almost everyone coming from a bearer-token API. If you send a key that is malformed or unrecognised, Google's API front end commonly rejects it as an invalid argument rather than as a failed authentication challenge — so you get a 400 with a status of INVALID_ARGUMENT and a message identifying the API key as the problem, where you were expecting 401 Unauthorized.

The practical consequence is that error handling written against the usual conventions will misclassify a bad Gemini key. Code that branches on "401 means fix the credential, 400 means fix the payload" will send a developer hunting through their request body for a mistake that is actually in their key. If you are writing a client for this API, key on the status field in the JSON body rather than the numeric code alone.

A missing key can surface differently again, sometimes as a 403. That is why the guidance here is to read the error body first: the numeric code narrows things down, but the status and message are what actually identify the fault.

403 — recognised, but not permitted

A PERMISSION_DENIED response means the request was understood and the caller identified, but the action is not allowed. On this API the usual causes are that the Generative Language API has not been enabled for the key's project, that the key carries an application restriction which your caller does not satisfy — the referrer and IP restrictions described above are the common ones — or that the key is restricted to a set of APIs that does not include this one. None of these are fixed by checking the key for typos. See 403 Forbidden for the underlying distinction between authentication and authorisation.

429 — resource exhausted

A RESOURCE_EXHAUSTED status with 429 Too Many Requests means you have exceeded a quota. Google's quotas are multi-dimensional — requests per minute, tokens per minute, requests per day, per model and per project — so hitting one while nowhere near another is normal and not a contradiction. The response message usually names the dimension that was exceeded, which tells you whether to throttle concurrency, reduce payload size, or request more quota. Retry with exponential backoff and jitter; a tight retry loop against a quota error simply burns the quota you have left.

404 — usually a model name, not a missing endpoint

When a generation request 404s, the cause is more often a model identifier in the path that does not exist or is not available to your project than a wrong base path. Compare it against the list your own /v1beta/models call returned.

Sending an actual generation request

Once the key checks out, the natural next step is a content generation call. On the Gemini API the model identifier is part of the URL path rather than the request body, with the action appended after a colon — a pattern that surprises people used to REST APIs where the verb lives in the method. The body carries a contents array of turns, each with a parts array.

POST https://generativelanguage.googleapis.com/v1beta/models/<MODEL>:generateContent
x-goog-api-key: <your key>
Content-Type: application/json

{
  "contents": [
    { "parts": [ { "text": "Say hello." } ] }
  ]
}

Substitute <MODEL> with an identifier from your own models listing. We are not hard-coding one here on purpose: model names on this platform are added and retired often enough that any specific value printed on a page like this would eventually mislead someone. Your own response is the authoritative source.

To run it in the console above: switch the method to POST, edit the URL, add Content-Type: application/json in the Headers tab, and paste the body into the Body tab. Format JSON will confirm the payload parses before you spend a request on it. Unlike the models listing, this consumes quota.

Gemini API keys and Vertex AI are not the same thing

A recurring source of confusion: Google offers Gemini models through two distinct surfaces. The Gemini API on the generativelanguage.googleapis.com host authenticates with a simple API key and is what AI Studio issues keys for — that is what this page covers. Vertex AI is the Google Cloud platform product, reached on Cloud endpoints and authenticated with Google Cloud credentials, typically an OAuth access token from a service account rather than an API key.

They have different hosts, different authentication, different request shapes in places, and different quota systems. A key that works against one is not a credential for the other. If you have followed a tutorial and are getting authentication errors that make no sense, check first that the tutorial and your credential refer to the same surface — that single mismatch explains a large share of "my Gemini key doesn't work" reports.

Provider APIs change — check the official docs

api-tester.com is an independent tool with no affiliation to, partnership with or endorsement from Google. Nothing here is official documentation. Endpoints, API versions, model names, error semantics and quotas are the provider's to change, and this page can fall behind. For current and authoritative detail, consult the official Gemini API documentation.

Note also that v1beta in the path is exactly what it says. Beta surfaces can change shape with less ceremony than stable ones, so verify the version prefix in the current docs before building on it.

We have deliberately not quoted prices, specific quota numbers or particular model identifiers here. Those change fastest, and a stale figure stated confidently is worse than none at all. What this page describes is the durable shape of the API: how it authenticates, how its errors are structured, and how to interpret them.

Test other providers and related tools

Frequently asked questions