DEV Community

Cover image for How to Use Gemini Embedding 2 API?
Preecha
Preecha

Posted on

How to Use Gemini Embedding 2 API?

How to Use the Gemini Embedding 2 API: A Practical Python Guide

Google’s Gemini Embedding 2 API generates embeddings for text, images, video, audio, and PDFs. This guide walks through the API with practical Python examples for semantic search, RAG, multimodal embeddings, and vector storage.

Try Apidog today

Note: This guide uses the public preview model gemini-embedding-2-preview. The API may change before general availability.

Want an overview before writing code? Read: What is Gemini Embedding 2?

Prerequisites

You need:

  • A Google AI API key
  • Python 3.7 or higher
  • The Google Generative AI SDK

Install the SDK 

pip install google-generativeai
Enter fullscreen mode Exit fullscreen mode

Configure the API Key

For quick experiments, configure the SDK directly:

import google.generativeai as genai

genai.configure([REDACTED CREDENTIAL])
Enter fullscreen mode Exit fullscreen mode

For production code, load the key from an environment variable:

import os
import google.generativeai as genai

[REDACTED CREDENTIAL]
genai.configure([REDACTED CREDENTIAL]
Enter fullscreen mode Exit fullscreen mode

Avoid hard-coding API keys in source code or committing them to version control.

Test the API with Apidog

Before integrating the API into your application, you can send a request directly from Apidog.

Image

  1. Create a new request in Apidog.
  2. Set the method to POST.
  3. Use this URL: 
   https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
Enter fullscreen mode Exit fullscreen mode
  1. Add the following header: 
   x-goog-[REDACTED CREDENTIAL]
Enter fullscreen mode Exit fullscreen mode
  1. Send this JSON body: 
   {
     "content": {
       "parts": [
         {
           "text": "What is API testing?"
         }
       ]
     }
   }
Enter fullscreen mode Exit fullscreen mode

Testing the request first lets you verify the API key and inspect the response structure before writing application code. You can also save the request as a test case and use it to validate embedding responses in a CI/CD pipeline.

Generate a Text Embedding

Text is the simplest embedding use case:

import google.generativeai as genai

genai.configure([REDACTED CREDENTIAL])

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="What is the meaning of life?"
)

embedding = result["embedding"]

print(f"Embedding dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")
Enter fullscreen mode Exit fullscreen mode

Example output:

Embedding dimensions: 3072
First 5 values: [0.0234, -0.0156, 0.0891, -0.0423, 0.0567]
Enter fullscreen mode Exit fullscreen mode

The embedding is returned as result["embedding"], a list of floating-point values. Each value represents one dimension of the vector.

Optimize Embeddings with Task Instructions

Use task_type to tell the model how you will use the embedding.

For search queries:

query_result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="best API testing tools",
    task_type="RETRIEVAL_QUERY"
)
Enter fullscreen mode Exit fullscreen mode

For documents that you will index:

doc_result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="Apidog is an API testing platform...",
    task_type="RETRIEVAL_DOCUMENT"
)
Enter fullscreen mode Exit fullscreen mode

Available task types include:

  • RETRIEVAL_QUERY — Search queries
  • RETRIEVAL_DOCUMENT — Documents being indexed
  • SEMANTIC_SIMILARITY — Comparing content similarity
  • CLASSIFICATION — Categorization tasks
  • CLUSTERING — Grouping similar content

Use matching task types for queries and indexed documents. For example, pair RETRIEVAL_QUERY with RETRIEVAL_DOCUMENT when building a search system.

Control the Output Dimensions

The default embedding size is 3072 dimensions. You can request a smaller vector to reduce storage requirements:

# Production-optimized: 768 dimensions
result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="Your text here",
    output_dimensionality=768
)
Enter fullscreen mode Exit fullscreen mode 
# Balanced: 1536 dimensions
result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="Your text here",
    output_dimensionality=1536
)
Enter fullscreen mode Exit fullscreen mode 
# Maximum quality: 3072 dimensions
result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content="Your text here",
    output_dimensionality=3072
)
Enter fullscreen mode Exit fullscreen mode

For many applications, 768 dimensions provide near-peak quality while using 75% less storage than 3072 dimensions.

Embed Images

Use image embeddings for visual search and image-based retrieval:

import PIL.Image

image = PIL.Image.open("product-photo.jpg")

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=image
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

You can include up to six images in one request:

import PIL.Image

images = [
    PIL.Image.open("image1.jpg"),
    PIL.Image.open("image2.jpg"),
    PIL.Image.open("image3.jpg")
]

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=images
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

Embed Video

To embed video, upload the file first and wait for processing:

import time
import google.generativeai as genai

video_file = genai.upload_file(path="demo-video.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=video_file
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

Video limits:

  • Maximum 128 seconds per request
  • Supported formats: MP4 and MOV
  • Supported codecs: H264, H265, AV1, and VP9

Embed Audio

The API can generate embeddings from audio without requiring a transcription:

import time
import google.generativeai as genai

audio_file = genai.upload_file(path="podcast-episode.mp3")

while audio_file.state.name == "PROCESSING":
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=audio_file
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

Audio limits:

  • Maximum 80 seconds per request
  • Supported formats: MP3 and WAV

Embed PDF Documents

Upload a PDF and wait for processing before generating its embedding:

import time
import google.generativeai as genai

pdf_file = genai.upload_file(path="user-manual.pdf")

while pdf_file.state.name == "PROCESSING":
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=pdf_file
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

PDF limits:

  • Maximum six pages per request
  • Processes both text and visual content

Create a Multimodal Embedding

You can combine different content types in one embedding:

import PIL.Image

image = PIL.Image.open("product.jpg")
text = "High-quality wireless headphones with noise cancellation"

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=[text, image]
)

embedding = result["embedding"]
Enter fullscreen mode Exit fullscreen mode

This represents the relationship between the text and image in a single vector.

Process Multiple Items

For a small collection, process each item in a loop:

texts = [
    "First document about API testing",
    "Second document about automation",
    "Third document about performance"
]

embeddings = []

for text in texts:
    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=text,
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768
    )
    embeddings.append(result["embedding"])

print(f"Generated {len(embeddings)} embeddings")
Enter fullscreen mode Exit fullscreen mode

For large batches, use the batch API when the workload is non-urgent. The batch API provides 50% cost savings according to the preview guidance.

Build a Semantic Search System

The following example embeds a set of documents, embeds a search query, and ranks documents by cosine similarity.

1. Install Dependencies 

pip install google-generativeai numpy scikit-learn
Enter fullscreen mode Exit fullscreen mode

2. Embed the Documents 

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure([REDACTED CREDENTIAL])

documents = [
    "Apidog is an API testing platform for developers",
    "REST APIs use HTTP methods like GET, POST, PUT, DELETE",
    "GraphQL provides a query language for APIs",
    "API documentation helps developers understand endpoints",
    "Postman is a popular API testing tool"
]

doc_embeddings = []

for doc in documents:
    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=doc,
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768
    )
    doc_embeddings.append(result["embedding"])

doc_embeddings = np.array(doc_embeddings)
Enter fullscreen mode Exit fullscreen mode

3. Define the Search Function 

def search(query, top_k=3):
    query_result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=query,
        task_type="RETRIEVAL_QUERY",
        output_dimensionality=768
    )

    query_embedding = np.array([query_result["embedding"]])

    similarities = cosine_similarity(
        query_embedding,
        doc_embeddings
    )[0]

    top_indices = np.argsort(similarities)[::-1][:top_k]

    return [
        {
            "document": documents[idx],
            "score": similarities[idx]
        }
        for idx in top_indices
    ]
Enter fullscreen mode Exit fullscreen mode

4. Run a Search 

results = search("What tools can I use for API testing?")

for i, result in enumerate(results, 1):
    print(f"{i}. Score: {result['score']:.4f}")
    print(f"   {result['document']}\n")
Enter fullscreen mode Exit fullscreen mode

Example output:

1. Score: 0.8234
   Apidog is an API testing platform for developers

2. Score: 0.7891
   Postman is a popular API testing tool

3. Score: 0.6543
   API documentation helps developers understand endpoints
Enter fullscreen mode Exit fullscreen mode

For production workloads, store the document embeddings in a vector database instead of recomputing them for every search.

Build a RAG System

Embeddings can provide the retrieval step in a Retrieval-Augmented Generation system.

1. Create a Knowledge Base 

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure([REDACTED CREDENTIAL])

knowledge_base = [
    "Apidog supports REST, GraphQL, and WebSocket APIs",
    "You can create test cases and run them automatically",
    "Apidog generates API documentation from your requests",
    "Mock servers help you test before the backend is ready",
    "Team collaboration features include shared workspaces"
]

kb_embeddings = []

for doc in knowledge_base:
    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=doc,
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768
    )
    kb_embeddings.append(result["embedding"])

kb_embeddings = np.array(kb_embeddings)
Enter fullscreen mode Exit fullscreen mode

2. Define the RAG Query Function 

def rag_query(question):
    # Embed the question
    query_result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=question,
        task_type="RETRIEVAL_QUERY",
        output_dimensionality=768
    )

    query_embedding = np.array([query_result["embedding"]])

    # Retrieve the most relevant context
    similarities = cosine_similarity(
        query_embedding,
        kb_embeddings
    )[0]

    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # Generate an answer using the retrieved context
    [REDACTED PROMPT]

Question: {question}

Answer the question based on the context provided."""

    model = genai.GenerativeModel("gemini-2.0-flash-exp")
    response = model.generate_content(prompt)

    return response.text
Enter fullscreen mode Exit fullscreen mode

3. Query the RAG System 

answer = rag_query("Can Apidog generate documentation?")
print(answer)
Enter fullscreen mode Exit fullscreen mode

This example retrieves the most relevant item from the knowledge base and passes it to a generative model as context.

For a larger RAG system, retrieve multiple results, include metadata with each document, and store the embeddings in a vector database.

Store Embeddings in ChromaDB

ChromaDB can store both documents and their embedding vectors:

import chromadb
import google.generativeai as genai

genai.configure([REDACTED CREDENTIAL])

client = chromadb.Client()
collection = client.create_collection(name="my_documents")

documents = [
    "API testing ensures your endpoints work correctly",
    "REST APIs follow stateless architecture principles",
    "GraphQL allows clients to request specific data"
]

for i, doc in enumerate(documents):
    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=doc,
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768
    )

    collection.add(
        embeddings=[result["embedding"]],
        documents=[doc],
        ids=[f"doc_{i}"]
    )
Enter fullscreen mode Exit fullscreen mode

Query the collection with a query embedding:

query = "How do I test my API?"

query_result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=query,
    task_type="RETRIEVAL_QUERY",
    output_dimensionality=768
)

results = collection.query(
    query_embeddings=[query_result["embedding"]],
    n_results=2
)

print("Top results:")

for doc in results["documents"][0]:
    print(f"- {doc}")
Enter fullscreen mode Exit fullscreen mode

Handle API Errors

Wrap embedding calls in exception handling so invalid input, quota limits, and timeouts do not crash your application:

import google.generativeai as genai
from google.api_core import exceptions

genai.configure([REDACTED CREDENTIAL])

def safe_embed(content):
    try:
        result = genai.embed_content(
            model="models/gemini-embedding-2-preview",
            content=content,
            output_dimensionality=768
        )
        return result["embedding"]

    except exceptions.InvalidArgument as error:
        print(f"Invalid input: {error}")
        # For example: content is too long or the format is unsupported.
        return None

    except exceptions.ResourceExhausted as error:
        print(f"Quota exceeded: {error}")
        # For example: a rate limit or quota limit was reached.
        return None

    except exceptions.DeadlineExceeded as error:
        print(f"Request timeout: {error}")
        return None

    except Exception as error:
        print(f"Unexpected error: {error}")
        return None
Enter fullscreen mode Exit fullscreen mode

Use the helper like this:

embedding = safe_embed("Your text here")

if embedding:
    print("Embedding generated successfully")
else:
    print("Failed to generate embedding")
Enter fullscreen mode Exit fullscreen mode

Common errors include:

Error Typical cause Suggested action
InvalidArgument Content exceeds the maximum length or uses an unsupported format Reduce or transform the input
ResourceExhausted Quota or rate limit exceeded Wait, retry, or review your plan
Unauthenticated The API key is invalid Check the configured key
PermissionDenied The model is unavailable to the project Verify the model name and access

Handle Rate Limits and Follow Best Practices

Keep these practices in mind:

  • Use 768 dimensions for production unless you need the quality of 3072 dimensions.
  • Process multiple items together when possible.
  • Cache embeddings for content that does not change.
  • Use task instructions for search, similarity, classification, or clustering.
  • Add retry logic with exponential backoff for transient failures.
  • Monitor token usage and API costs.
  • Respect the rate limits for your account.

The preview guidance lists the free tier at 60 requests per minute, while paid-tier limits vary by plan.

Optimize Costs

Use Smaller Vectors 

result = genai.embed_content(
    model="models/gemini-embedding-2-preview",
    content=text,
    output_dimensionality=768
)
Enter fullscreen mode Exit fullscreen mode

Using 768 dimensions requires 75% less storage than 3072 dimensions.

Use Batch Processing

Use the batch API for non-urgent workloads:

# Batch API implementation depends on your setup.
# Batch processing provides 50% cost savings.
Enter fullscreen mode Exit fullscreen mode

Cache Embeddings

A simple in-memory cache can prevent duplicate embedding requests:

import hashlib

embedding_cache = {}

def get_embedding_cached(content):
    cache_key = hashlib.md5(content.encode()).hexdigest()

    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=content,
        output_dimensionality=768
    )

    embedding_cache[cache_key] = result["embedding"]

    return result["embedding"]
Enter fullscreen mode Exit fullscreen mode

For production, use a persistent cache and include the model, task type, and output dimensionality in the cache key.

Troubleshoot Common Issues

Invalid API Key

Check that the environment variable exists:

import os

[REDACTED CREDENTIAL]

if not [REDACTED CREDENTIAL] key not set!")
Enter fullscreen mode Exit fullscreen mode

Content Is Too Long

Split long text into smaller chunks before embedding:

def chunk_text(text, max_tokens=8000):
    words = text.split()
    chunks = []
    current_chunk = []

    for word in words:
        current_chunk.append(word)

        if len(current_chunk) >= max_tokens:
            chunks.append(" ".join(current_chunk))
            current_chunk = []

    if current_chunk:
        chunks.append(" ".join(current_chunk))

    return chunks
Enter fullscreen mode Exit fullscreen mode

Embed each chunk separately:

for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=chunk
    )
Enter fullscreen mode Exit fullscreen mode

File Processing Times Out

Large files may remain in the PROCESSING state for several minutes. Add a maximum wait time:

import time
import google.generativeai as genai

video_file = genai.upload_file(path="large-video.mp4")

max_wait = 300
waited = 0

while video_file.state.name == "PROCESSING" and waited < max_wait:
    time.sleep(5)
    waited += 5
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "PROCESSING":
    print("File processing timeout")
else:
    result = genai.embed_content(
        model="models/gemini-embedding-2-preview",
        content=video_file
    )
Enter fullscreen mode Exit fullscreen mode

Next Steps

You can now use Gemini Embedding 2 to:

  • Build semantic search for technical documentation
  • Create a RAG application with multimodal context
  • Implement visual search for product catalogs
  • Add audio search for podcast or video content
  • Compare dimensions and quality to optimize storage costs

Start with text embeddings, then add images, video, or audio as your use case requires.

Before deploying, test the Gemini API endpoints, validate response formats, and automate your embedding pipeline tests with Apidog.

Top comments (0)