Google

Gemini API (Google AI)

Prompt Gemini models, stream, call functions, ground in Google Search, upload files, cache context, embed text and generate images.

AI & machine learningGuided#gemini#llm#google#chat#embeddings#vision#image-generation

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Gemini API (Google AI for Developers) gives your code Google's Gemini models: text and chat, reasoning, code, reading images, PDFs, audio and video, calling your own functions, answering with Google Search results, embeddings for search and clustering, and image generation. It is served from generativelanguage.googleapis.com. This collection covers the classic generateContent family of endpoints, which Google says stays fully supported, plus the newer Interactions API (/v1beta/interactions) that Google now recommends for new projects.

Get an API key

  1. Open Google AI Studio > API keys and sign in with a Google account. Accept the terms; first-time users get a default Google Cloud project and a key created for them.
  2. If you already use Google Cloud, open Dashboard > Projects, choose Import projects and import the project you want to bill, then go to API Keys and choose Create API key for it.
  3. Restrict the key: on the API Keys page, keys marked Unrestricted should be set to Restrict to Gemini API only. Unrestricted standard keys are rejected, and long-dormant unrestricted keys get blocked.
  4. To go past the free tier, set up billing for the project in AI Studio (billing guide).
  5. Paste the key into the apiKey variable of this collection. It is marked secret, so it is never shown or shared when you fork or publish.

Authentication and base URL

Every request sends the key in the x-goog-api-key header; the collection sets it for you. (Google's curl samples sometimes put it in a ?key= query parameter instead; the header keeps it out of logs.) Never ship the key in a browser or mobile app.

Base URL: https://generativelanguage.googleapis.com/v1beta. v1 is the stable surface; v1beta carries everything in v1 plus newer features (Files, caching, grounding, Interactions), so this collection uses it. File uploads go to https://generativelanguage.googleapis.com/upload/v1beta/files.

Models

The model variable defaults to gemini-4-hydrogen, which Google recommends for new projects (fast, good at coding and agent work). gemini-4-carbon is the strongest reasoner, gemini-4-argon sits between them, and gemini-3.5-flash-lite is the low-cost option. Embeddings use gemini-embedding-2, image generation uses gemini-nano-banana-2.1. Gemini 2.5 Flash and 2.5 Pro are deprecated. Run List models to see what your key can use, and see the models page.

How to use this collection

  • Fill in apiKey, then run 1. Start here (list models, send a prompt, count tokens).
  • 2. Prompting covers system instructions, chat history, thinking level, streaming and JSON output.
  • 3. Tools is a function-calling round trip (the first request saves the call id and thought signature for the second) plus Google Search grounding.
  • 4. Images and files sends an inline image and walks through the resumable Files upload; the upload saves fileName and fileUri for the requests after it.
  • 5. Embeddings, 6. Context caching (needs a large uploaded file), 7. Image generation and 8. Interactions API cover the rest.

Common errors

StatusCodeWhat to do
400INVALID_ARGUMENTMalformed body, misspelled field, or a feature the model or API version does not support. Read error.message. Missing thought signatures in a function-calling turn also return 400.
400FAILED_PRECONDITIONFree tier not available in your country: enable billing on the project.
403PERMISSION_DENIEDKey wrong, blocked, leaked or unrestricted, or the project needs verification or billing.
404NOT_FOUNDWrong model ID, or a file or cache that no longer exists (uploaded files expire after 48 hours).
429RESOURCE_EXHAUSTEDRate or spend limit hit: back off and retry, or request a higher limit.
500 / 503 / 504INTERNAL / UNAVAILABLE / DEADLINE_EXCEEDEDTemporary or input too large: shorten the input, retry with backoff, or try another model.

Errors come back as {"error": {"code", "message", "status", "details"}}. A blocked prompt is not an HTTP error: check promptFeedback.blockReason and each candidate's finishReason.

Limits and pricing

There is a free tier with lower limits and a paid tier billed per input and output token, with different rates per model; Google Search grounding on newer models is billed per search query. Limits are per project and shown in AI Studio. See Pricing, Rate limits, Errors and the API reference.

Endpoints 30

1. Start here

  • GETList models/modelsLists the models your key can call. Each entry has name (models/<id>; drop the models/ prefix when you put it in the model variable), displayName,…
  • GETGet one model/models/{{model}}Returns one model's details: token limits, supported methods, whether it thinks, and its default and maximum temperature, topP and topK. Change {{model}} in…
  • POSTGenerate text/models/{{model}}:generateContentThe core call: POST /models/{model}:generateContent. Send contents (a list of turns, each with a role and parts) and get back candidates. Reading the answer:…
  • POSTCount tokens/models/{{model}}:countTokensCounts the tokens a prompt will use, without generating anything (free). Send either contents, or a full generateContentRequest (with model, contents, and…

2. Prompting

  • POSTSystem instruction/models/{{model}}:generateContentsystemInstruction sets the model's role, tone and rules for the whole request, separately from the user's turns. It is a content object with text parts (no…
  • POSTMulti-turn chat/models/{{model}}:generateContentgenerateContent is stateless: to continue a conversation, send the whole history every time, alternating user and model turns, ending with the new user turn.…
  • POSTGeneration config: thinking and length/models/{{model}}:generateContentgenerationConfig controls how the answer is produced. Lower thinking is faster and cheaper; higher thinking helps maths, planning and code. Gemini 3.6 Flash…
  • POSTStream the answer (SSE)/models/{{model}}:streamGenerateContent:streamGenerateContent?alt=sse takes the same body as generateContent but returns Server-Sent Events while the answer is written. Each data: line is a partial…
  • POSTStructured JSON output/models/{{model}}:generateContentMakes the model answer with JSON that matches your schema. Put it under generationConfig.responseFormat.text: mimeType: "APPLICATION_JSON" and schema (a JSON…

3. Tools

  • POST1) Declare a function/models/{{model}}:generateContentDescribe your functions in tools[].functionDeclarations (name, description, and parameters as an OpenAPI-style schema with lowercase types). When the model…
  • POST2) Send the function result back/models/{{model}}:generateContentSend the full history again: the user's question, the model's turn copied exactly (the functionCall part with its thoughtSignature), then a user turn with a…
  • POSTGround answers in Google Search/models/{{model}}:generateContentAdd the googleSearch tool and the model decides when to search the web, then answers with fresh information. The candidate gains groundingMetadata: Google's…

4. Images and files

  • POSTImage input (inline base64)/models/{{model}}:generateContentPut an image (or a short PDF or audio clip) straight into a part as inlineData with mimeType and base64 data, next to a text part with your question. Use it…
  • POST1) Start a resumable uploadhttps://generativelanguage.googleapis.com/upload/v1beta/filesUploads are two requests. This one announces the file and gets back an upload URL in the x-goog-upload-url response header (the test script saves it into…
  • POST2) Upload the bytes and finalize{{uploadUrl}}Sends the file to the uploadUrl from the previous request and finishes the upload in one go. Choose the same file in the body tab (binary). Headers:…
  • GETGet file/{{fileName}}Returns one file's metadata. {{fileName}} already contains the files/ prefix (set by the upload). Check state: PROCESSING (not usable yet), ACTIVE (ready) or…
  • GETList files/filesLists the files your project has uploaded and that have not expired, newest first. Use pageSize and the returned nextPageToken (as pageToken) to page through…
  • POSTUse the uploaded file in a prompt/models/{{model}}:generateContentReference the file with a fileData part (fileUri and mimeType) instead of sending its bytes, next to your instruction. The same file can be reused in many…
  • DELETEDelete a file/{{fileName}}Deletes an uploaded file now instead of waiting for the 48-hour expiry. Returns an empty object {} on success; a 404 means it was already gone.

5. Embeddings

  • POSTEmbed one input/models/{{embeddingModel}}:embedContentReturns one vector for the content you send. The URL uses the embeddingModel variable (gemini-embedding-2, multimodal, 8,192 input tokens); the body repeats…
  • POSTEmbed many inputs (batch)/models/{{embeddingModel}}:batchEmbedContentsEmbeds up to many inputs in one call: requests is a list where each item has its own model (must match the URL), content and optional embedContentConfig. The…

6. Context caching

  • POSTCreate a cache/cachedContentsStores contents (and optionally systemInstruction and tools) for one model. model is models/<id> and the cache only works with that model. ttl is a duration…
  • POSTAsk using the cache/models/{{cacheModel}}:generateContentPass the cache's name in cachedContent and send only the new question in contents. The model must be the one the cache was created for, and you cannot also…
  • PATCHExtend a cache's lifetime/{{cacheName}}Only the expiry can change after creation. Send a new ttl (counted from now) or an expireTime. Returns the updated cache. To change the cached content itself,…
  • GETList caches/cachedContentsLists your caches with their names, models and expiry times (cached content itself is never returned). Use it to find caches you forgot to delete, since…
  • DELETEDelete a cache/{{cacheName}}Deletes the cache now and stops storage charges. Returns {}. Requests that still reference it will then fail with 404 or 403.

7. Image generation

  • POSTGenerate an image/models/{{imageModel}}:generateContentImage models answer through the same generateContent call. Set generationConfig.responseModalities to ["TEXT", "IMAGE"] (or just ["IMAGE"]) and optionally…

8. Interactions API

  • POSTCreate an interaction/interactionsSends input (a string, or a list of content or step objects) to model and returns an interaction with an id, a status (completed, requires_action when a…
  • POSTContinue the conversation/interactionsPass the previous interaction's id as previous_interaction_id and send only the new message: the server supplies the earlier turns (and any thought…
  • GETGet an interaction/interactions/{{interactionId}}Fetches a stored interaction by id with its status, steps and usage. Use it to poll work started with background: true, or to read back a past conversation.…

API details

Base URL
https://generativelanguage.googleapis.com/v1beta
Authentication
An API key in the x-goog-api-key header
Operations
30 operations on 30 pathsPOST 21GET 6DELETE 2PATCH 1
Main resources
1. Start here 42. Prompting 53. Tools 34. Images and files 75. Embeddings 26. Context caching 57. Image generation 18. Interactions API 3
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Gemini API (Google AI) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Gemini API (Google AI) collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the x-goog-api-key header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List models” (GET /models), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Gemini API (Google AI)?

Prompt Gemini models, stream, call functions, ground in Google Search, upload files, cache context, embed text and generate images. It is listed under AI & machine learning and has 30 endpoints.

Who publishes the Gemini API (Google AI)?

It is listed from Google's public API description (an OpenAPI document), not published by Google on Swastik Codes. Anyone who controls googleapis.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Gemini API (Google AI)?

Requests go to https://generativelanguage.googleapis.com/v1beta. Endpoint paths are added to this base URL.

How do I authenticate with the Gemini API (Google AI)?

With an API key in the x-goog-api-key header.

How many endpoints does the Gemini API (Google AI) have?

30 operations on 30 paths (21 POST, 6 GET, 2 DELETE, 1 PATCH). The largest groups are 1. Start here, 2. Prompting, 3. Tools, 4. Images and files.

Is forking the Gemini API (Google AI) free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.