Gemini Embeddings API
Generate text embeddings using Google Gemini API via REST.
Prerequisites
-
Environment variable GOOGLE_API_KEY must be set
-
API endpoint: https://generativelanguage.googleapis.com/v1beta
-
Model: gemini-embedding-001
Workflow
Phase 1: Determine Embedding Type
-
Single Embedding: For one text input
-
Batch Embedding: For multiple texts (more efficient)
Phase 2: Configure Task Type (Optional)
Choose based on use case:
-
RETRIEVAL_QUERY : For search queries
-
RETRIEVAL_DOCUMENT : For documents to be searched
-
SEMANTIC_SIMILARITY : For comparing text similarity
-
CLASSIFICATION : For text classification
-
CLUSTERING : For grouping similar texts
Phase 3: Execute API Call
- Single Text Embedding
Basic Embedding
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"model": "models/gemini-embedding-001",
"content": {
"parts": [{"text": "Hello world"}]
}
}'
With Task Type
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"model": "models/gemini-embedding-001",
"content": {
"parts": [{"text": "What is machine learning?"}]
},
"task_type": "RETRIEVAL_QUERY"
}'
With Output Dimensionality Control
Truncate embeddings to a smaller size for efficiency:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"model": "models/gemini-embedding-001",
"content": {
"parts": [{"text": "Hello world"}]
},
"output_dimensionality": 256
}'
- Batch Embedding
Process multiple texts in a single API call:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"requests": [
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "What is the meaning of life?"}]}
},
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "How does the brain work?"}]}
},
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "What is quantum computing?"}]}
}
]
}'
Batch with Task Type
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"requests": [
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "Document about AI"}]},
"task_type": "RETRIEVAL_DOCUMENT"
},
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "Document about ML"}]},
"task_type": "RETRIEVAL_DOCUMENT"
}
]
}'
Response Structure
Single Embedding Response
{ "embedding": { "values": [ -0.02342152, 0.01676572, 0.009261323, ... ] } }
Batch Embedding Response
{ "embeddings": [ { "values": [-0.022374554, -0.004560777, ...] }, { "values": [-0.007975887, -0.02141119, ...] }, { "values": [-0.0047850125, 0.008764064, ...] } ] }
Task Types Reference
Task Type Use Case Example
RETRIEVAL_QUERY
Search queries "What is machine learning?"
RETRIEVAL_DOCUMENT
Documents to search Article content, wiki pages
SEMANTIC_SIMILARITY
Compare text similarity Duplicate detection
CLASSIFICATION
Categorize text Spam detection, sentiment
CLUSTERING
Group similar texts Topic modeling
Common Use Cases
RAG (Retrieval-Augmented Generation)
-
Embed documents with RETRIEVAL_DOCUMENT
-
Store embeddings in vector database
-
Embed user query with RETRIEVAL_QUERY
-
Find similar documents by vector similarity
Semantic Search
Embed the query
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "How to train a neural network?"}]},
"task_type": "RETRIEVAL_QUERY"
}'
Text Similarity Comparison
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents?key=$GOOGLE_API_KEY"
-H 'Content-Type: application/json'
-d '{
"requests": [
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "The cat sat on the mat"}]},
"task_type": "SEMANTIC_SIMILARITY"
},
{
"model": "models/gemini-embedding-001",
"content": {"parts": [{"text": "A feline rested on the rug"}]},
"task_type": "SEMANTIC_SIMILARITY"
}
]
}'
Then compute cosine similarity between the two embedding vectors.
Best Practices
-
Use batch embedding: More efficient for multiple texts
-
Set task_type: Improves embedding quality for specific use cases
-
Reduce dimensionality: Use output_dimensionality for smaller, faster embeddings when full precision isn't needed
-
Match task types: Use same task_type for queries and documents in RAG
-
Normalize vectors: Cosine similarity works best with normalized vectors