Google Gemini API

Getting Started

Obtain a free API key at Google AI Studio.

Set the API key in your shell.

export GEMINI_API_KEY="[api_key]"

Run a quick connectivity test.

curl "https://generativelanguage.googleapis.com/v1beta/models?key=[api_key]" | jq '.models[].name'

Generate Content

Basic Text Generation

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "[prompt]"}]
    }]
  }'

With System Instruction

Parameters:

• system_instruction (Optional): Sets persistent instructions that apply to every turn.

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {
      "parts": [{"text": "You are a senior DevOps engineer. Be concise. Use bullet points."}]
    },
    "contents": [{
      "parts": [{"text": "[prompt]"}]
    }]
  }'

Multi-Turn Conversation

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user",  "parts": [{"text": "What is a Kubernetes pod?"}]},
      {"role": "model", "parts": [{"text": "A pod is the smallest deployable unit in Kubernetes..."}]},
      {"role": "user",  "parts": [{"text": "How does it differ from a deployment?"}]}
    ]
  }'

Streaming Response

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:streamGenerateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "[prompt]"}]
    }]
  }'

Generation Config

Control output behaviour with generationConfig:

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "[prompt]"}]}],
    "generationConfig": {
      "temperature":     0.2,
      "topP":            0.9,
      "topK":            40,
      "maxOutputTokens": 2048,
      "stopSequences":   ["END"],
      "responseMimeType": "application/json"
    }
  }'

💡 Tip: Set responseMimeType: "application/json" to force valid JSON output without a schema requirement.

Structured Output (JSON Schema)

Force output to match an exact JSON schema:

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "List the top 3 Linux distributions with their primary use case."}]}],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name":     {"type": "string"},
            "use_case": {"type": "string"}
          },
          "required": ["name", "use_case"]
        }
      }
    }
  }'

Vision — Analyze Images

Image from URL

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Describe what is shown in this image."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/diagram.jpg"}}
      ]
    }]
  }'

Image from Local File (Base64)

Encode the local image as base64.

IMG_B64=$(base64 -w 0 /path/to/image.png)

Send the base64 payload to Gemini.

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "What does this diagram show?"},
        {"inlineData": {"mimeType": "image/png", "data": "'"$IMG_B64"'"}}
      ]
    }]
  }'

File API (Large Inputs)

Upload a File

Use for files >20MB or for reuse across requests (audio, video, documents):

Upload the file first.

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=[api_key]" \
  -H "X-Goog-Upload-Command: start, upload, finalize" \
  -H "X-Goog-Upload-Header-Content-Type: application/pdf" \
  -H "Content-Type: application/json" \
  -d '{"file": {"display_name": "report.pdf"}}' \
  --upload-file /path/to/report.pdf

Use the returned file URI in a request.

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Summarize the key findings of this document."},
        {"fileData": {"mimeType": "application/pdf", "fileUri": "https://generativelanguage.googleapis.com/v1beta/files/FILE_ID"}}
      ]
    }]
  }'

List Uploaded Files

curl "https://generativelanguage.googleapis.com/v1beta/files?key=[api_key]"

Delete a File

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/files/FILE_ID?key=[api_key]"

Function Calling / Tools

Define Tools

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {"parts": [{"text": "Use tools when needed."}]},
    "contents": [{"parts": [{"text": "What is the current price of AAPL?"}]}],
    "tools": [{
      "functionDeclarations": [{
        "name": "get_stock_price",
        "description": "Get the current stock price for a ticker symbol.",
        "parameters": {
          "type": "object",
          "properties": {
            "ticker":   {"type": "string", "description": "Stock ticker, e.g. AAPL"},
            "currency": {"type": "string", "enum": ["USD","EUR","GBP"]}
          },
          "required": ["ticker"]
        }
      }]
    }],
    "toolConfig": {"functionCallingConfig": {"mode": "AUTO"}}
  }'

💡 Tip: toolConfig.functionCallingConfig.mode can be AUTO, ANY (force a call), or NONE.

Code Execution

Let Gemini write and run Python code in a sandboxed environment:

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Calculate the first 20 Fibonacci numbers and plot them."}]}],
    "tools": [{"codeExecution": {}}]
  }'

Grounding with Google Search

Attach live web search results to ground responses in current facts:

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:generateContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "What are the latest kernel changes in Linux 6.x?"}]}],
    "tools": [{"googleSearch": {}}]
  }'

Embeddings

Parameters:

• task_type (Optional): Hint for expected use — RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, SEMANTIC_SIMILARITY, CLASSIFICATION.

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/text-embedding-004",
    "content": {"parts": [{"text": "How does Rust handle memory safety?"}]},
    "taskType": "RETRIEVAL_QUERY"
  }'

Batch Embeddings

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContents?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"model": "models/text-embedding-004", "content": {"parts": [{"text": "First document"}]}},
      {"model": "models/text-embedding-004", "content": {"parts": [{"text": "Second document"}]}}
    ]
  }'

Token Counting

curl "https://generativelanguage.googleapis.com/v1beta/models/[model]:countTokens?key=[api_key]" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "[prompt]"}]}]
  }'

Models Reference

Key Parameters

Error Handling

Resources

• Gemini API Reference
• Google AI Studio
• Gemini Cookbook (GitHub)
• Model Overview
• Pricing