API Reference Fresh 🌱

Complete API reference for Gemini Embedding 2 (gemini-embedding-2-preview).

Endpoint

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent

Authentication

Method	Header
API Key	x-goog-api-key: YOUR_API_KEY
OAuth 2.0	Authorization: Bearer YOUR_TOKEN

Request Format

Request Body (REST)

{
  "content": {
    "parts": [
      { "text": "Your text here" }
    ]
  },
  "taskType": "RETRIEVAL_QUERY",
  "outputDimensionality": 768
}

Request Body (Image via REST)

{
  "content": {
    "parts": [
      {
        "inline_data": {
          "mime_type": "image/png",
          "data": "BASE64_ENCODED_DATA"
        }
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Default	Description
content	Content	Yes	-	The content to embed
content.parts	Part[]	Yes	-	Array of content parts
taskType	string	No	-	Optimization hint (see Task Types)
outputDimensionality	integer	No	3072	Output vector size (128-3072)

Content Part Types

Part Type	Fields	Use For
Text	{ "text": "..." }	Plain text
Inline Data	{ "inline_data": { "mime_type": "...", "data": "..." } }	Images, video, audio, PDF

Supported MIME Types

Modality	MIME Types
Image	image/png, image/jpeg
Video	video/mp4, video/quicktime
Audio	audio/mp3, audio/wav
Document	application/pdf

Task Types

Task Type	Code	Best For
Semantic Similarity	SEMANTIC_SIMILARITY	Comparing two texts for meaning overlap
Classification	CLASSIFICATION	Categorizing text into preset labels
Clustering	CLUSTERING	Grouping similar texts together
Retrieval (Document)	RETRIEVAL_DOCUMENT	Indexing documents for search
Retrieval (Query)	RETRIEVAL_QUERY	Encoding search queries
Code Retrieval	CODE_RETRIEVAL_QUERY	Finding code via natural language
Question Answering	QUESTION_ANSWERING	Finding documents that answer questions
Fact Verification	FACT_VERIFICATION	Verifying claims against sources

Task Type Pairing

For search/retrieval, use RETRIEVAL_DOCUMENT when indexing and RETRIEVAL_QUERY when searching. This asymmetric pairing gives the best results.

Response Format

{
  "embeddings": [
    {
      "values": [0.0123, -0.0456, 0.0789, ...]
    }
  ]
}

Field	Type	Description
embeddings	Embedding[]	Array of embedding objects
embeddings[].values	float[]	Vector of floating-point numbers

Input Limits

Modality	Limit
Text	8,192 tokens
Images	6 per request
Video	128 seconds (MP4/MOV, H264/H265/AV1/VP9)
Audio	80 seconds (MP3/WAV)
PDF	6 pages
Overall	8,192 tokens across all modalities combined

Embedding Behavior

Scenario	Result
Single content with multiple parts	One aggregated embedding
Multiple entries in contents array	Separate embedding per entry
No task type specified	General-purpose embedding
Dimensions below 3072	Normalization recommended

SDK Examples

Python

from google import genai
from google.genai import types

client = genai.Client()

# Text
result = client.models.embed_content(
    model='gemini-embedding-2-preview',
    contents='Your text',
    config=types.EmbedContentConfig(
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
)

# Image
result = client.models.embed_content(
    model='gemini-embedding-2-preview',
    contents=[
        types.Part.from_bytes(data=image_bytes, mime_type='image/png')
    ]
)

JavaScript

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});

// Text
const response = await ai.models.embedContent({
    model: 'gemini-embedding-2-preview',
    contents: 'Your text',
});

// Image
const response = await ai.models.embedContent({
    model: 'gemini-embedding-2-preview',
    contents: [{
        inlineData: { mimeType: 'image/png', data: imgBase64 }
    }],
});

cURL

# Text
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{"content": {"parts": [{"text": "Hello world"}]}}'

# Image
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{"content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_B64}"'"}}]}}'

HTTP Status Codes

Code	Meaning	Action
200	Success	Parse response normally
400	Bad Request	Check input format and content
401	Unauthorized	Verify API key
403	Forbidden	Check API enablement and quotas
429	Rate Limited	Implement exponential backoff
500	Server Error	Retry with backoff

See Also

• Getting Started — Setup and first request
• Pricing — Cost details
• Troubleshooting — Error resolution