gemini-api（Gemini API 文档）

Gemini API (REST)

Delegate tasks to Gemini 3 series models. Requires GEMINI_API_KEY environment variable.

Models

Defaults:

• Text output tasks (text generation, vision, OCR): Use gemini-3.1-pro-preview
• Image output tasks (image generation, editing): Use gemini-3-pro-image-preview

Variant: gemini-3.1-pro-preview-customtools — use if the standard model ignores your custom tools in favor of bash commands.

API Endpoint

POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:generateContent?key={API_KEY}

Request Structure

For text models (with thinking):

{
  "contents": [{"parts": [{"text": "..."}]}],
  "generationConfig": {
    "thinkingConfig": {"thinkingLevel": "high"}
  }
}

Temperature: For all Gemini 3 models, keep temperature at its default of 1.0. Lowering it may cause looping or degraded reasoning.

For image models (no thinking support):

{
  "contents": [{"parts": [{"text": "..."}]}],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"]
  }
}

Thinking Levels (Text models only)

Notes:

• Image models (gemini-3-pro-image-preview, gemini-2.5-flash-image) do NOT support thinking levels.
• Levels are relative allowances, not strict token guarantees.
• Do NOT combine thinkingLevel with the legacy thinking_budget — it triggers a 400 error.

Thought Signatures (Multi-turn / Function Calling)

Gemini 3 returns encrypted thoughtSignature fields on model response parts. These MUST be echoed back in subsequent requests to maintain reasoning context.

Rules:

• Single function call → return the signature on the functionCall part
• Parallel function calls → only the first call carries a signature; return all parts in order
• Sequential multi-step → accumulate ALL signatures across turns

Official SDKs (Python, Node, Java) handle signatures automatically. For REST API, you must manage them manually in conversation history.

Examples

1. Text Generation (Gemini 3.1 Pro)

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain quantum entanglement simply"}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "high"}}
  }' | jq -r '.candidates[0].content.parts[0].text'

2. Image Understanding / Vision (Gemini 3.1 Pro)

Analyze an image - use Gemini 3.1 Pro for vision tasks (text output):

IMAGE_B64=$(base64 -i photo.jpg)

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"inlineData": {"mimeType": "image/jpeg", "data": "'"${IMAGE_B64}"'"}},
        {"text": "Describe this image in detail. What objects, people, or text do you see?"}
      ]
    }],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "high"}}
  }' | jq -r '.candidates[0].content.parts[0].text'

3. Image Generation (Nano Banana Pro)

Generate images using Nano Banana Pro:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A cozy coffee shop interior, warm lighting, watercolor style"}]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' | base64 -d > coffee_shop.png

4. Image Editing (Nano Banana Pro)

Edit images using Nano Banana Pro:

IMAGE_B64=$(base64 -i input.jpg)

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"inlineData": {"mimeType": "image/jpeg", "data": "'"${IMAGE_B64}"'"}},
        {"text": "Remove the background and make it transparent"}
      ]
    }],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' | base64 -d > edited.png

5. Text in Images (Nano Banana Pro)

Nano Banana Pro excels at rendering text:

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Create a professional business card for \"Jane Smith, CEO\" at \"TechCorp Inc\" with modern minimalist design"}]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' | base64 -d > business_card.png

6. Fast Tasks (Flash models - only when speed needed)

# Fast text/vision (gemini-3-flash-preview)
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "Quick summary"}]}]}' | jq -r '.candidates[0].content.parts[0].text'

# Fast image generation (gemini-2.5-flash-image)
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A simple icon"}]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' | base64 -d > icon.png

When to Delegate to Gemini

Response Structure

Text response:

{"candidates": [{"content": {"parts": [{"text": "..."}]}}]}

Image response:

{"candidates": [{"content": {"parts": [
  {"text": "Here is your image..."},
  {"inlineData": {"mimeType": "image/png", "data": "<base64>"}}
]}}]}

Python Script

Use scripts/gemini_api.py (prioritizes Pro models):

# Text generation (defaults to gemini-3.1-pro-preview)
python scripts/gemini_api.py text "Explain REST APIs"

# With medium thinking (3.1 Pro only)
python scripts/gemini_api.py text "Summarize this" --thinking medium

# Image understanding (defaults to gemini-3.1-pro-preview)
python scripts/gemini_api.py vision photo.jpg "What's in this image?"

# Image generation (defaults to Nano Banana Pro)
python scripts/gemini_api.py generate "A sunset over mountains" -o sunset.png

# Image editing (defaults to Nano Banana Pro)
python scripts/gemini_api.py edit input.jpg "Add a rainbow" -o output.png

# Fast mode (only when user requests speed)
python scripts/gemini_api.py text "Quick question" --model flash
python scripts/gemini_api.py vision photo.jpg "Quick check" --model flash
python scripts/gemini_api.py generate "Simple icon" -o icon.png --model flash