2576 Embedding Spec 1fb6e3cb

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 theEmbeddings 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 ourProhibited Use PolicyandGoogle'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 inputContentusing the specifiedGemini Embedding model.

Endpoint

posthttps:``/``/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 themodels.listmethod.

Format:models/{model}It takes the formmodels/{model}.

Request body

The request body contains data with the following structure: Fieldscontent``object (Content)
Required. The content to embed. Only theparts.textfields will be counted. taskType``enum (TaskType)
Optional. Optional task type for which the embeddings will be used. Not supported on earlier models (models/embedding-001). title``string
Optional. An optional title for the text. Only applicable when TaskType isRETRIEVAL_DOCUMENT.

Note: Specifying atitleforRETRIEVAL_DOCUMENTprovides better quality embeddings for retrieval. outputDimensionality``integer
Optional. 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).

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)  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/python/embed.py#L22-L32

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);  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/javascript/embed.js#L22-L31

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))  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/go/embed.go#L15-L41

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?"}]}
    }'  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/rest/embed.sh#L4-L12

Response body

If successful, the response body contains an instance ofEmbedContentResponse.

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 inputContentwhich consists of a batch of strings represented asEmbedContentRequestobjects.

Endpoint

posthttps:``/``/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 themodels.listmethod.

Format:models/{model}It takes the formmodels/{model}.

Request body

The request body contains data with the following structure: Fieldsrequests[]``object (EmbedContentRequest)
Required. Embed requests for the batch. The model in each of these requests must match the model specifiedBatchEmbedContentsRequest.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)  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/python/embed.py#L37-L51

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);  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/javascript/embed.js#L38-L51

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))  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/go/embed.go#L48-L75

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  
https://github.com/google-gemini/api-examples/blob/856e8a0f566a2810625cecabba6e2ab1fe97e496/rest/embed.sh#L16-L34

Response body

The response to aBatchEmbedContentsRequest.

If successful, the response body contains data with the following structure: Fieldsembeddings[]``object (ContentEmbedding)
Output only. The embeddings for each request, in the same order as provided in the batch request.

Method: models.asyncBatchEmbedContent

• Endpoint
• Path parameters
• Request body
  • JSON representation
    • JSON representation
    • JSON representation
    • JSON representation
• Response body
• Authorization scopes

Enqueues a batch ofmodels.embedContentrequests for batch processing. We have amodels.batchEmbedContentshandler inGenerativeService, but it was synchronized. So we name this one to beAsyncto avoid confusion.

Endpoint

posthttps:``/``/generativelanguage.googleapis.com``/v1beta``/{batch.model=models``/*}:asyncBatchEmbedContent

Path parameters

batch.model``string
Required. The name of theModelto use for generating the completion.

Format:models/{model}. It takes the formmodels/{model}.

Request body

The request body contains data with the following structure: Fieldsbatch.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 ofOperation.

EmbedContentResponse

• JSON representation

The response to anEmbedContentRequest. Fieldsembedding``object (ContentEmbedding)
Output only. The embedding generated from the input content.

ContentEmbedding

• JSON representation

A list of floats representing an embedding. Fieldsvalues[]``number
The embedding values.

TaskType

Type of task for which the embedding will be used.

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 ofEmbedContentrequests. Fieldsmodel``string
Required. The name of theModelto 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.

InputEmbedContentConfig

Configures the input to the batch request. Fields
source``Union type
Required. The source of the input.sourcecan be only one of the following: fileName``string
The name of theFilecontaining the input requests. requests``object (InlinedEmbedContentRequests)
The requests to be processed in the batch.

InlinedEmbedContentRequests

The requests to be processed in the batch if provided as part of the batch creation request. Fieldsrequests[]``object (InlinedEmbedContentRequest)
Required. The requests to be processed in the batch.

InlinedEmbedContentRequest

The request to be processed in the batch. Fieldsrequest``object (EmbedContentRequest)
Required. The request to be processed in the batch. metadata``object (Struct format)
Optional. The metadata to be associated with the request.

EmbedContentBatchOutput

The output of a batch request. This is returned in theAsyncBatchEmbedContentResponseor theEmbedContentBatch.outputfield. Fields
output``Union type
The output of the batch request.outputcan 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 beEmbedContentResponsemessages 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.

InlinedEmbedContentResponses

The responses to the requests in the batch. FieldsinlinedResponses[]``object (InlinedEmbedContentResponse)
Output only. The responses to the requests in the batch.

InlinedEmbedContentResponse

The response to a single request in the batch. Fieldsmetadata``object (Struct format)
Output only. The metadata associated with the request.
output``Union type
The output of the request.outputcan 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.

EmbedContentBatchStats

Stats about the batch. FieldsrequestCount``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.