Embeddings  |  Gemini API  |  Google AI for Developers
Skip to main content
/
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어
Get API key
Cookbook
Community
Sign in
Docs
API reference
Gemini API
Docs
API reference
Get API key
Cookbook
Community
Overview
API versions
Core APIs
Interactions API
GenerateContent
Real time APIs
Live API
Live Music API
Platform APIs
Model API
Agents
Webhooks
Triggers
Batch API
Files API
Tokens
Caching
Embeddings
File Search API
File search stores
Documents
All methods
SDK references
Python
Go
TypeScript
Java
C#
The Interactions API is now generally available. We recommend using this API for access to all the latest features and models.
Home
Gemini API
API reference
Send feedback
Embeddings
Embeddings are a numerical representation of text input that open up a number of unique use cases, such as clustering, similarity measurement and information retrieval. For an introduction, check out the Embeddings guide.
Unlike generative AI models that create new content, the Gemini Embedding model is only intended to transform the format of your input data into a numerical representation. While Google is responsible for providing an embedding model that transforms the format of your input data to the numerical-format requested, users retain full responsibility for the data they input and the resulting embeddings. By using the Gemini Embedding model you confirm that you have the necessary rights to any content that you upload. Do not generate content that infringes on others' intellectual property or privacy rights. Your use of this service is subject to our Prohibited Use Policy and Google's Terms of Service.
Method: models.embedContent
Endpoint
Path parameters
Request body
JSON representation
Response body
Authorization scopes
Example request
Basic
Generates a text embedding vector from the input Content using the specified Gemini Embedding model.
Endpoint
post
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent
Path parameters
model
string
Required. The model's resource name. This serves as an ID for the Model to use.
This name should match a model name returned by the models.list method.
Format: models/{model} It takes the form models/{model}.
Request body
The request body contains data with the following structure:
Fields
content
object (Content)
Required. The content to embed. Only the parts.text fields will be counted.
taskType
(deprecated)
enum (TaskType)
Optional. Deprecated: Please use EmbedContentConfig.task_type instead. Optional task type for which the embeddings will be used. Not supported on earlier models (models/embedding-001).
title
(deprecated)
string
Optional. Deprecated: Please use EmbedContentConfig.title instead. An optional title for the text. Only applicable when TaskType is RETRIEVAL_DOCUMENT.
Note: Specifying a title for RETRIEVAL_DOCUMENT provides better quality embeddings for retrieval.
outputDimensionality
(deprecated)
integer
Optional. Deprecated: Please use EmbedContentConfig.output_dimensionality instead. Optional reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end. Supported by newer models since 2024 only. You cannot set this value if using the earlier model (models/embedding-001).
embedContentConfig
object (EmbedContentConfig)
Optional. Configuration for the models.embedContent request.
Example request
Python
from google import genai
from google.genai import types
client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
model="gemini-embedding-001",
contents=text,
config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
embed.py
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
model: "gemini-embedding-001",
contents: text,
config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js
Go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey:  os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001",
contents, &genai.EmbedContentConfig{
OutputDimensionality: &outputDim,
})
if err != nil {
log.Fatal(err)
}
embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(embeddings))
embed.go
Shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
"content": {
"parts":[{
"text": "What is the meaning of life?"}]}
}'
embed.sh
Response body
If successful, the response body contains an instance of EmbedContentResponse.
Method: models.batchEmbedContents
Endpoint
Path parameters
Request body
JSON representation
Response body
JSON representation
Authorization scopes
Example request
Basic
Generates multiple embedding vectors from the input Content which consists of a batch of strings represented as EmbedContentRequest objects.
Endpoint
post
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents
Path parameters
model
string
Required. The model's resource name. This serves as an ID for the Model to use.
This name should match a model name returned by the models.list method.
Format: models/{model} It takes the form models/{model}.
Request body
The request body contains data with the following structure:
Fields
requests[]
object (EmbedContentRequest)
Required. Embed requests for the batch. The model in each of these requests must match the model specified BatchEmbedContentsRequest.model.
Example request
Python
from google import genai
from google.genai import types
client = genai.Client()
texts = [
"What is the meaning of life?",
"How much wood would a woodchuck chuck?",
"How does the brain work?",
]
result = client.models.embed_content(
model="gemini-embedding-001",
contents=texts,
config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)
embed.py
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
"What is the meaning of life?",
"How much wood would a woodchuck chuck?",
"How does the brain work?",
];
const result = await ai.models.embedContent({
model: "gemini-embedding-001",
contents: texts,
config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js
Go
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey:  os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
contents := []*genai.Content{
genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}
outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
OutputDimensionality: &outputDim,
})
if err != nil {
log.Fatal(err)
}
embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(embeddings))
embed.go
Shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_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 much wood would a woodchuck chuck?"}]}, },
{
"model": "models/gemini-embedding-001",
"content": {
"parts":[{
"text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values
embed.sh
Response body
The response to a BatchEmbedContentsRequest.
If successful, the response body contains data with the following structure:
Fields
embeddings[]
object (ContentEmbedding)
Output only. The embeddings for each request, in the same order as provided in the batch request.
usageMetadata
object (EmbeddingUsageMetadata)
Output only. The usage metadata for the request.
JSON representation
{
"embeddings": [
{
object (ContentEmbedding)
}
],
"usageMetadata": {
object (EmbeddingUsageMetadata)
}
}
Method: models.asyncBatchEmbedContent
Endpoint
Path parameters
Request body
JSON representation
JSON representation
JSON representation
JSON representation
Response body
Authorization scopes
Enqueues a batch of models.embedContent requests for batch processing. We have a models.batchEmbedContents handler in GenerativeService, but it was synchronized. So we name this one to be Async to avoid confusion.
Endpoint
post
https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent
Path parameters
batch.model
string
Required. The name of the Model to use for generating the completion.
Format: models/{model}. It takes the form models/{model}.
Request body
The request body contains data with the following structure:
Fields
batch.name
string
Output only. Identifier. Resource name of the batch.
Format: batches/{batchId}.
batch.displayName
string
Required. The user-defined name of this batch.
batch.inputConfig
object (InputEmbedContentConfig)
Required. Input configuration of the instances on which batch processing are performed.
batch.output
object (EmbedContentBatchOutput)
Output only. The output of the batch request.
batch.createTime
string (Timestamp format)
Output only. The time at which the batch was created.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
batch.endTime
string (Timestamp format)
Output only. The time at which the batch processing completed.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
batch.updateTime
string (Timestamp format)
Output only. The time at which the batch was last updated.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
batch.batchStats
object (EmbedContentBatchStats)
Output only. Stats about the batch.
batch.state
enum (BatchState)
Output only. The state of the batch.
batch.priority
string (int64 format)
Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.
Response body
If successful, the response body contains an instance of Operation.
EmbedContentResponse
JSON representation
The response to an EmbedContentRequest.
Fields
embedding
object (ContentEmbedding)
Output only. The embedding generated from the input content.
usageMetadata
object (EmbeddingUsageMetadata)
Output only. The usage metadata for the request.
JSON representation
{
"embedding": {
object (ContentEmbedding)
},
"usageMetadata": {
object (EmbeddingUsageMetadata)
}
}
ContentEmbedding
JSON representation
A list of floats representing an embedding.
Fields
values[]
number
The embedding values. This is for 3P users only and will not be populated for 1P calls.
shape[]
integer
This field stores the soft tokens tensor frame shape (e.g. [1, 1, 256, 2048]).
JSON representation
{
"values": [
number
],
"shape": [
integer
]
}
TaskType
Type of task for which the embedding will be used.
Enums
TASK_TYPE_UNSPECIFIED
Unset value, which will default to one of the other enum values.
RETRIEVAL_QUERY
Specifies the given text is a query in a search/retrieval setting.
RETRIEVAL_DOCUMENT
Specifies the given text is a document from the corpus being searched.
SEMANTIC_SIMILARITY
Specifies the given text will be used for STS.
CLASSIFICATION
Specifies that the given text will be classified.
CLUSTERING
Specifies that the embeddings will be used for clustering.
QUESTION_ANSWERING
Specifies that the given text will be used for question answering.
FACT_VERIFICATION
Specifies that the given text will be used for fact verification.
CODE_RETRIEVAL_QUERY
Specifies that the given text will be used for code retrieval.
EmbedContentBatch
JSON representation
InputEmbedContentConfig
JSON representation
InlinedEmbedContentRequests
JSON representation
InlinedEmbedContentRequest
JSON representation
EmbedContentBatchOutput
JSON representation
InlinedEmbedContentResponses
JSON representation
InlinedEmbedContentResponse
JSON representation
EmbedContentBatchStats
JSON representation
A resource representing a batch of EmbedContent requests.
Fields
model
string
Required. The name of the Model to use for generating the completion.
Format: models/{model}.
name
string
Output only. Identifier. Resource name of the batch.
Format: batches/{batchId}.
displayName
string
Required. The user-defined name of this batch.
inputConfig
object (InputEmbedContentConfig)
Required. Input configuration of the instances on which batch processing are performed.
output
object (EmbedContentBatchOutput)
Output only. The output of the batch request.
createTime
string (Timestamp format)
Output only. The time at which the batch was created.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime
string (Timestamp format)
Output only. The time at which the batch processing completed.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime
string (Timestamp format)
Output only. The time at which the batch was last updated.
Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
batchStats
object (EmbedContentBatchStats)
Output only. Stats about the batch.
state
enum (BatchState)
Output only. The state of the batch.
priority
string (int64 format)
Optional. The priority of the batch. Batches with a higher priority value will be processed before batches with a lower priority value. Negative values are allowed. Default is 0.
JSON representation
{
"model": string,
"name": string,
"displayName": string,
"inputConfig": {
object (InputEmbedContentConfig)
},
"output": {
object (EmbedContentBatchOutput)
},
"createTime": string,
"endTime": string,
"updateTime": string,
"batchStats": {
object (EmbedContentBatchStats)
},
"state": enum (BatchState),
"priority": string
}
InputEmbedContentConfig
Configures the input to the batch request.
Fields
source
Union type
Required. The source of the input. source can be only one of the following:
fileName
string
The name of the File containing the input requests.
requests
object (InlinedEmbedContentRequests)
The requests to be processed in the batch.
JSON representation
{
// source
"fileName": string,
"requests": {
object (InlinedEmbedContentRequests)
}
// Union type
}
InlinedEmbedContentRequests
The requests to be processed in the batch if provided as part of the batch creation request.
Fields
requests[]
object (InlinedEmbedContentRequest)
Required. The requests to be processed in the batch.
JSON representation
{
"requests": [
{
object (InlinedEmbedContentRequest)
}
]
}
InlinedEmbedContentRequest
The request to be processed in the batch.
Fields
request
object (EmbedContentRequest)
Required. The request to be processed in the batch.
metadata
object (Struct format)
Optional. The metadata to be associated with the request.
JSON representation
{
"request": {
object (EmbedContentRequest)
},
"metadata": {
object
}
}
EmbedContentBatchOutput
The output of a batch request. This is returned in the AsyncBatchEmbedContentResponse or the EmbedContentBatch.output field.
Fields
output
Union type
The output of the batch request. output can be only one of the following:
responsesFile
string
Output only. The file ID of the file containing the responses. The file will be a JSONL file with a single response per line. The responses will be EmbedContentResponse messages formatted as JSON. The responses will be written in the same order as the input requests.
inlinedResponses
object (InlinedEmbedContentResponses)
Output only. The responses to the requests in the batch. Returned when the batch was built using inlined requests. The responses will be in the same order as the input requests.
JSON representation
{
// output
"responsesFile": string,
"inlinedResponses": {
object (InlinedEmbedContentResponses)
}
// Union type
}
InlinedEmbedContentResponses
The responses to the requests in the batch.
Fields
inlinedResponses[]
object (InlinedEmbedContentResponse)
Output only. The responses to the requests in the batch.
JSON representation
{
"inlinedResponses": [
{
object (InlinedEmbedContentResponse)
}
]
}
InlinedEmbedContentResponse
The response to a single request in the batch.
Fields
metadata
object (Struct format)
Output only. The metadata associated with the request.
output
Union type
The output of the request. output can be only one of the following:
error
object (Status)
Output only. The error encountered while processing the request.
response
object (EmbedContentResponse)
Output only. The response to the request.
JSON representation
{
"metadata": {
object
},
// output
"error": {
object (Status)
},
"response": {
object (EmbedContentResponse)
}
// Union type
}
EmbedContentBatchStats
Stats about the batch.
Fields
requestCount
string (int64 format)
Output only. The number of requests in the batch.
successfulRequestCount
string (int64 format)
Output only. The number of requests that were successfully processed.
failedRequestCount
string (int64 format)
Output only. The number of requests that failed to be processed.
pendingRequestCount
string (int64 format)
Output only. The number of requests that are still pending processing.
JSON representation
{
"requestCount": string,
"successfulRequestCount": string,
"failedRequestCount": string,
"pendingRequestCount": string
}
EmbedContentConfig
JSON representation
Configurations for the EmbedContent request.
Fields
title
string
Optional. The title for the text.
taskType
enum (TaskType)
Optional. The task type of the embedding.
autoTruncate
boolean
Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.
outputDimensionality
integer
Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.
documentOcr
boolean
Optional. Whether to enable OCR for document content.
audioTrackExtraction
boolean
Optional. Whether to extract audio from video content.
JSON representation
{
"title": string,
"taskType": enum (TaskType),
"autoTruncate": boolean,
"outputDimensionality": integer,
"documentOcr": boolean,
"audioTrackExtraction": boolean
}
EmbeddingUsageMetadata
JSON representation
Metadata on the usage of the embedding request.
Fields
promptTokenCount
integer
Output only. Number of tokens in the prompt.
promptTokenDetails[]
object (ModalityTokenCount)
Output only. List of modalities that were processed in the request input.
JSON representation
{
"promptTokenCount": integer,
"promptTokenDetails": [
{
object (ModalityTokenCount)
}
]
}
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-05-20 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-05-20 UTC."],[],[]]
Terms
Privacy
Manage cookies
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어