Repository Public
1<br />23The Gemini API offers embedding models to generate embeddings for text, images,4video, and other content. These resulting embeddings can then be used for tasks5such as semantic search, classification, and clustering, providing more accurate,6context-aware results than keyword-based approaches.78The latest model, `gemini-embedding-2`, is the first multimodal9embedding model in the Gemini API. It maps text, images,10video, audio, and documents into a unified embedding space, enabling cross-modal11search, classification, and clustering across over 100 languages. See the12[multimodal embeddings section](https://ai.google.dev/gemini-api/docs/embeddings#multimodal) to learn more. For text-only13use cases, `gemini-embedding-001` remains available.1415Building Retrieval Augmented Generation (RAG) systems is a common use case for16AI products. Embeddings play a key role in significantly enhancing model outputs17with improved factual accuracy, coherence, and contextual richness. If you prefer18to use a managed RAG solution, we built the [File Search](https://ai.google.dev/gemini-api/docs/file-search)19tool which makes doing RAG easier to manage and more cost effective.2021## Generating embeddings2223Use the `embedContent` method to generate text embeddings:2425### Python2627 from google import genai2829 client = genai.Client()3031 result = client.models.embed_content(32 model="gemini-embedding-2",33 contents="What is the meaning of life?"34 )3536 print(result.embeddings)3738### JavaScript3940 import { GoogleGenAI } from "@google/genai";4142 async function main() {4344 const ai = new GoogleGenAI({});4546 const response = await ai.models.embedContent({47 model: 'gemini-embedding-2',48 contents: 'What is the meaning of life?',49 });5051 console.log(response.embeddings);52 }5354 main();5556### Java5758 import com.google.genai.Client;59 import com.google.genai.types.EmbedContentResponse;6061 Client client = new Client();6263 EmbedContentResponse response =64 client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", null);6566 System.out.println(response.embeddings().orElse(null));6768### Go6970 package main7172 import (73 "context"74 "encoding/json"75 "fmt"76 "log"7778 "google.golang.org/genai"79 )8081 func main() {82 ctx := context.Background()83 client, err := genai.NewClient(ctx, nil)84 if err != nil {85 log.Fatal(err)86 }8788 contents := []*genai.Content{89 genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),90 }91 result, err := client.Models.EmbedContent(ctx,92 "gemini-embedding-2",93 contents,94 nil,95 )96 if err != nil {97 log.Fatal(err)98 }99100 embeddings, err := json.MarshalIndent(result.Embeddings, "", " ")101 if err != nil {102 log.Fatal(err)103 }104 fmt.Println(string(embeddings))105 }106107### REST108109 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \110 -H "Content-Type: application/json" \111 -H "x-goog-api-key: ${GEMINI_API_KEY}" \112 -d '{113 "model": "models/gemini-embedding-2",114 "content": {115 "parts": [{116 "text": "What is the meaning of life?"117 }]118 }119 }'120121> [!NOTE]122> **Note:** While `gemini-embedding-001` lets you generate individual embeddings for a list of strings, Gemini Embedding 2 produces a single aggregated embedding for multiple inputs. You can find more information in [Embedding aggregation](https://ai.google.dev/gemini-api/docs/embeddings#embedding-aggregation), or you can use the [Batch API](https://ai.google.dev/gemini-api/docs/batch-api#batch-embedding) if you want to generate multiple embeddings at once.123124## Specify task type to improve performance125126You can use embeddings for a wide range of tasks from classification to document127search. Specifying the right task type helps optimize the embeddings for the128intended relationships, maximizing accuracy and efficiency.129130### Task types with Embeddings 2131132For text-only tasks with `gemini-embedding-2`, we strongly recommend you133add the task instruction in your prompt. This can be done by formatting the134query and the document with the correct task prefix.135136When generating a [single embedding based on multimodal137input](https://ai.google.dev/gemini-api/docs/embeddings#embedding-aggregation), we generally don't recommend prefixing the text138portion of the input with a task instruction. In some cases it improves139performance, but in others it reduces performance.140141The following tables show examples of how to format queries and documents for142symmetric and asymmetric use cases using the `gemini-embedding-2` model.143144**Retrieval use cases (Asymmetric format)**145146In asymmetric use cases, add the task prefix to the query and apply147the document structure for the content you want to embed and retrieve.148149| Use case | Query structure | Document structure |150|---|---|---|151| Search query | `task: search result | query: {content}` | `title: {title} | text: {content}` If there is no title, use `title: none`. |152| Question answering | `task: question answering | query: {content}` | `title: {title} | text: {content}` |153| Fact checking | `task: fact checking | query: {content}` | `title: {title} | text: {content}` |154| Code retrieval | `task: code retrieval | query: {content}` | `title: {title} | text: {content}` |155156**Example usage**157158### Python159160 # Generate embedding for a task's query. Use your correct task here:161 def prepare_query(query):162 # return f"task: question answering | query: {query}"163 # return f"task: fact checking | query: {query}"164 # return f"task: code retrieval | query: {query}"165 return f"task: search result | query: {query}"166167 # Generate embedding for document of an asymmetric retrieval task:168 def prepare_document(content, title=None):169 if title is None:170 title = "none"171 return f"title: {title} | text: {content}"172173**Single-input use cases (Symmetric format)**174175In symmetric use cases, for the same task, use the same formatting176for the query and the document.177178| Use case | Input structure |179|---|---|180| Classification | `task: classification | query: {content}` |181| Clustering | `task: clustering | query: {content}` |182| Semantic similarity | `task: sentence similarity | query: {content}` Do not use this for search or retrieval. It is intended for semantic textual similarity. |183184**Example usage**185186### Python187188 # Generate embedding for query & document of your task.189 def prepare_query_and_document(content):190 # return f'task: clustering | query: {content}'191 # return f'task: sentence similarity | query: {content}'192 return f'task: classification | query: {content}'193194It is important that the task is used consistently. E.g., if documents are195embedded with `f'task: classification | query: {content}'`, the query should196also be embedded following this task format.197198### Task types with Embeddings 1199200For `gemini-embedding-001`, you can specify the `task_type` in the `embedContent`201method. For a complete list of supported task types, see the [Supported task types](https://ai.google.dev/gemini-api/docs/embeddings#supported-task-types)202table.203204> [!NOTE]205> **Note:** You cannot use the `task_type` field for the `gemini-embedding-2` model. Instead, include the task as an instruction in your prompt, as detailed in the [above section](https://ai.google.dev/gemini-api/docs/embeddings#task-types-embeddings-2).206207The following example shows how you can use `SEMANTIC_SIMILARITY` to check how208similar in meaning strings of texts are.209210### Python211212 from google import genai213 from google.genai import types214 import pandas as pd215 from sklearn.metrics.pairwise import cosine_similarity216217 client = genai.Client()218219 texts = [220 "What is the meaning of life?",221 "What is the purpose of existence?",222 "How do I bake a cake?",223 ]224225 result = client.models.embed_content(226 model="gemini-embedding-001",227 contents=texts,228 config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")229 )230231 # Create a 3x3 table to show the similarity matrix232 df = pd.DataFrame(233 cosine_similarity([e.values for e in result.embeddings]),234 index=texts,235 columns=texts,236 )237238 print(df)239240### JavaScript241242 import { GoogleGenAI } from "@google/genai";243 // npm i compute-cosine-similarity244 import * as cosineSimilarity from "compute-cosine-similarity";245246 async function main() {247 const ai = new GoogleGenAI({});248249 const texts = [250 "What is the meaning of life?",251 "What is the purpose of existence?",252 "How do I bake a cake?",253 ];254255 const response = await ai.models.embedContent({256 model: 'gemini-embedding-001',257 contents: texts,258 config: { taskType: 'SEMANTIC_SIMILARITY' },259 });260261 const embeddings = response.embeddings.map(e => e.values);262263 for (let i = 0; i < texts.length; i++) {264 for (let j = i + 1; j < texts.length; j++) {265 const text1 = texts[i];266 const text2 = texts[j];267 const similarity = cosineSimilarity(embeddings[i], embeddings[j]);268 console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);269 }270 }271 }272273 main();274275### Java276277 import java.util.Arrays;278 import com.google.genai.Client;279 import com.google.genai.types.ContentEmbedding;280 import com.google.genai.types.EmbedContentConfig;281 import com.google.genai.types.EmbedContentResponse;282 import java.util.List;283284 Client client = new Client();285286 List<String> texts =287 Arrays.asList(288 "What is the meaning of life?",289 "What is the purpose of existence?",290 "How do I bake a cake?");291292 EmbedContentConfig config =293 EmbedContentConfig.builder().taskType("SEMANTIC_SIMILARITY").build();294295 EmbedContentResponse response =296 client.models.embedContent("gemini-embedding-001", texts, config);297298 List<ContentEmbedding> embeddings = response.embeddings().get();299300 for (int i = 0; i < texts.size(); i++) {301 for (int j = i + 1; j < texts.size(); j++) {302 List<Float> v1 = embeddings.get(i).values().get();303 List<Float> v2 = embeddings.get(j).values().get();304 double dotProduct = 0.0;305 double normA = 0.0;306 double normB = 0.0;307 for (int k = 0; k < v1.size(); k++) {308 dotProduct += v1.get(k) * v2.get(k);309 normA += v1.get(k) * v1.get(k);310 normB += v2.get(k) * v2.get(k);311 }312 double similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));313 System.out.printf(314 "Similarity between '%s' and '%s': %.4f%n", texts.get(i), texts.get(j), similarity);315 }316 }317318### Go319320 package main321322 import (323 "context"324 "fmt"325 "log"326 "math"327328 "google.golang.org/genai"329 )330331 // cosineSimilarity calculates the similarity between two vectors.332 func cosineSimilarity(a, b []float32) (float64, error) {333 if len(a) != len(b) {334 return 0, fmt.Errorf("vectors must have the same length")335 }336337 var dotProduct, aMagnitude, bMagnitude float64338 for i := 0; i < len(a); i++ {339 dotProduct += float64(a[i] * b[i])340 aMagnitude += float64(a[i] * a[i])341 bMagnitude += float64(b[i] * b[i])342 }343344 if aMagnitude == 0 || bMagnitude == 0 {345 return 0, nil346 }347348 return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil349 }350351 func main() {352 ctx := context.Background()353 client, _ := genai.NewClient(ctx, nil)354 defer client.Close()355356 texts := []string{357 "What is the meaning of life?",358 "What is the purpose of existence?",359 "How do I bake a cake?",360 }361362 var contents []*genai.Content363 for _, text := range texts {364 contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))365 }366367 result, _ := client.Models.EmbedContent(ctx,368 "gemini-embedding-001",369 contents,370 &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},371 )372373 embeddings := result.Embeddings374375 for i := 0; i < len(texts); i++ {376 for j := i + 1; j < len(texts); j++ {377 similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)378 fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)379 }380 }381 }382383### REST384385 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \386 -H "Content-Type: application/json" \387 -H "x-goog-api-key: $GEMINI_API_KEY" \388 -d '{389 "taskType": "SEMANTIC_SIMILARITY",390 "content": {391 "parts": [392 {393 "text": "What is the meaning of life?"394 },395 {396 "text": "How much wood would a woodchuck chuck?"397 },398 {399 "text": "How does the brain work?"400 }401 ]402 }403 }'404405The code snippets will show how similar the different chunks of text are to one406another when run.407408> [!NOTE]409> **Note:** Cosine similarity is a good distance metric because it focuses on direction rather than magnitude, which more accurately reflects conceptual closeness. Values range from -1 (opposite) to 1 (greatest similarity).410411#### Supported task types412413Supported task types for `gemini-embedding-001`:414415| Task type | Description | Examples |416|---|---|---|417| **SEMANTIC_SIMILARITY** | Embeddings optimized to assess text similarity. | Recommendation systems, duplicate detection |418| **CLASSIFICATION** | Embeddings optimized to classify texts according to preset labels. | Sentiment analysis, spam detection |419| **CLUSTERING** | Embeddings optimized to cluster texts based on their similarities. | Document organization, market research, anomaly detection |420| **RETRIEVAL_DOCUMENT** | Embeddings optimized for document search. | Indexing articles, books, or web pages for search. |421| **RETRIEVAL_QUERY** | Embeddings optimized for general search queries. Use `RETRIEVAL_QUERY` for queries; `RETRIEVAL_DOCUMENT` for documents to be retrieved. | Custom search |422| **CODE_RETRIEVAL_QUERY** | Embeddings optimized for retrieval of code blocks based on natural language queries. Use `CODE_RETRIEVAL_QUERY` for queries; `RETRIEVAL_DOCUMENT` for code blocks to be retrieved. | Code suggestions and search |423| **QUESTION_ANSWERING** | Embeddings for questions in a question-answering system, optimized for finding documents that answer the question. Use `QUESTION_ANSWERING` for questions; `RETRIEVAL_DOCUMENT` for documents to be retrieved. | Chatbox |424| **FACT_VERIFICATION** | Embeddings for statements that need to be verified, optimized for retrieving documents that contain evidence supporting or refuting the statement. Use `FACT_VERIFICATION` for the target text; `RETRIEVAL_DOCUMENT` for documents to be retrieved | Automated fact-checking systems |425426## Controlling embedding size427428Both `gemini-embedding-001` and `gemini-embedding-2` are trained using429the Matryoshka Representation Learning (MRL) technique which teaches a model to430learn high-dimensional embeddings that have initial segments (or prefixes) which431are also useful, simpler versions of the same data.432433Use the `output_dimensionality` parameter to control the size of434the output embedding vector. Selecting a smaller output dimensionality can save435storage space and increase computational efficiency for downstream applications,436while sacrificing little in terms of quality. By default, both models output a4373072-dimensional embedding, but you can truncate it to a smaller size without438losing quality to save storage space. We recommend using 768, 1536, or 3072439output dimensions.440441### Python442443 from google import genai444 from google.genai import types445446 client = genai.Client()447448 result = client.models.embed_content(449 model="gemini-embedding-2",450 contents="What is the meaning of life?",451 config=types.EmbedContentConfig(output_dimensionality=768)452 )453454 [embedding_obj] = result.embeddings455 embedding_length = len(embedding_obj.values)456457 print(f"Length of embedding: {embedding_length}")458459### JavaScript460461 import { GoogleGenAI } from "@google/genai";462463 async function main() {464 const ai = new GoogleGenAI({});465466 const response = await ai.models.embedContent({467 model: 'gemini-embedding-2',468 contents: 'What is the meaning of life?',469 config: { outputDimensionality: 768 },470 });471472 const embeddingLength = response.embeddings[0].values.length;473 console.log(`Length of embedding: ${embeddingLength}`);474 }475476 main();477478### Java479480 import com.google.genai.Client;481 import com.google.genai.types.ContentEmbedding;482 import com.google.genai.types.EmbedContentConfig;483 import com.google.genai.types.EmbedContentResponse;484485 Client client = new Client();486487 EmbedContentConfig config =488 EmbedContentConfig.builder().outputDimensionality(768).build();489490 EmbedContentResponse response =491 client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);492493 ContentEmbedding embeddingObj = response.embeddings().get().get(0);494 int embeddingLength = embeddingObj.values().get().size();495496 System.out.println("Length of embedding: " + embeddingLength);497498### Go499500 package main501502 import (503 "context"504 "fmt"505 "log"506507 "google.golang.org/genai"508 )509510 func main() {511 ctx := context.Background()512 // The client uses Application Default Credentials.513 // Authenticate with 'gcloud auth application-default login'.514 client, err := genai.NewClient(ctx, nil)515 if err != nil {516 log.Fatal(err)517 }518 defer client.Close()519520 contents := []*genai.Content{521 genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),522 }523524 result, err := client.Models.EmbedContent(ctx,525 "gemini-embedding-2",526 contents,527 &genai.EmbedContentRequest{OutputDimensionality: 768},528 )529 if err != nil {530 log.Fatal(err)531 }532533 embedding := result.Embeddings[0]534 embeddingLength := len(embedding.Values)535 fmt.Printf("Length of embedding: %d\n", embeddingLength)536 }537538### REST539540 curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \541 -H 'Content-Type: application/json' \542 -H "x-goog-api-key: $GEMINI_API_KEY" \543 -d '{544 "content": {"parts":[{ "text": "What is the meaning of life?"}]},545 "output_dimensionality": 768546 }'547548Example output from the code snippet:549550 Length of embedding: 768551552## Ensuring quality for smaller dimensions553554> [!NOTE]555> **Note:** `gemini-embedding-2` introduces automatic renormalization for non-default dimensions.556557While the default 3072-dimension embeddings are always normalized, Gemini558Embedding 2 also auto-normalizes truncated dimensions (e.g., 768, 1536). This559ensures semantic similarity is calculated via vector direction rather than560magnitude, providing more accurate results out of the box.561562**Older Models** : If you are using `gemini-embedding-001`, you must manually563normalize non-3072 dimensions as follows:564565### Python566567 import numpy as np568 from numpy.linalg import norm569570 # Only for embeddings from `gemini-embedding-001`571 embedding_values_np = np.array(embedding_obj.values)572 normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)573574 print(f"Normed embedding length: {len(normed_embedding)}")575 print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1576577Example output from this code snippet:578579 Normed embedding length: 768580 Norm of normed embedding: 1.000000581582The following table shows the MTEB scores, a commonly used benchmark for583embeddings, for different dimensions. Notably, the result shows that performance584is not strictly tied to the size of the embedding dimension, with lower585dimensions achieving scores comparable to their higher dimension counterparts.586587| MRL Dimension | MTEB Score (Gemini Embedding 001) |588|---|---|589| 2048 | 68.16 |590| 1536 | 68.17 |591| 768 | 67.99 |592| 512 | 67.55 |593| 256 | 66.19 |594| 128 | 63.31 |595596## Multimodal embeddings597598The `gemini-embedding-2` model supports multimodal input, allowing you599to embed images, video, audio, and documents content alongside text. All modalities600are mapped into the same embedding space, enabling cross-modal search and601comparison.602603### Supported modalities and limits604605The overall maximum input tokens limit is 8192 tokens.606607| Modality | Specifications and limits |608|---|---|609| **Text** | Supports up to 8,192 tokens. |610| **Image** | Maximum of 6 images per request. Supported formats: PNG, JPEG. |611| **Audio** | Maximum duration of 180 seconds. Supported formats: MP3, WAV. |612| **Video** | Maximum duration of 120 seconds. Supported formats: MP4, MOV. Supported codecs: H264, H265, AV1, VP9. The system processes a maximum of 32 frames per video: short videos (≤32s) are sampled at 1 fps, while longer videos are uniformly sampled to 32 frames. Audio tracks are not processed in video files. |613| **Documents (PDF)** | Maximum of 1 file per request, up to 6 pages. |614615### Embedding images616617The following example shows how to embed an image using618`gemini-embedding-2`.619620Images can be provided as inline data or as uploaded files621through the [Files API](https://ai.google.dev/gemini-api/docs/files).622623### Python624625 from google import genai626 from google.genai import types627628 with open('example.png', 'rb') as f:629 image_bytes = f.read()630631 client = genai.Client()632633 result = client.models.embed_content(634 model='gemini-embedding-2',635 contents=[636 types.Part.from_bytes(637 data=image_bytes,638 mime_type='image/png',639 ),640 ]641 )642643 print(result.embeddings)644645### JavaScript646647 import { GoogleGenAI } from "@google/genai";648 import * as fs from "node:fs";649650 async function main() {651 const ai = new GoogleGenAI({});652653 const imgBase64 = fs.readFileSync("example.png", { encoding: "base64" });654655 const response = await ai.models.embedContent({656 model: 'gemini-embedding-2',657 contents: [{658 inlineData: {659 mimeType: 'image/png',660 data: imgBase64,661 },662 }],663 });664665 console.log(response.embeddings);666 }667668 main();669670### Java671672 import com.google.genai.Client;673 import com.google.genai.types.Content;674 import com.google.genai.types.EmbedContentResponse;675 import com.google.genai.types.Part;676 import java.nio.file.Files;677 import java.nio.file.Paths;678679 Client client = new Client();680681 byte[] imageBytes = Files.readAllBytes(Paths.get("example.png"));682683 Content content = Content.fromParts(Part.fromBytes(imageBytes, "image/png"));684685 EmbedContentResponse response =686 client.models.embedContent("gemini-embedding-2", content, null);687688 System.out.println(response.embeddings().orElse(null));689690### REST691692 IMG_PATH="/path/to/your/image.png"693 IMG_BASE64=$(base64 -w0 "${IMG_PATH}")694695 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \696 -H "Content-Type: application/json" \697 -H "x-goog-api-key: ${GEMINI_API_KEY}" \698 -d '{699 "content": {700 "parts": [{701 "inline_data": {702 "mime_type": "image/png",703 "data": "'"${IMG_BASE64}"'"704 }705 }]706 }707 }'708709### Embedding aggregation710711When working with multimodal content, how you structure your input affects the712embedding output:713714- **Multiple parts (aggregated):** Adding multiple inputs directly to the `contents` parameter produces one aggregated embedding for all inputs.715- **Multiple `Content` objects (separate):** Wrapping each input in a `Content` object and passing them in the `contents` parameter returns separate embeddings for each entry.716- **Post-level representation:** For complex objects like social media posts with multiple media items, we recommend aggregating separate embeddings (for example, by averaging) to create a coherent post-level representation.717718The following example shows how to create one aggregated embedding for text and719image input. Simply add multiple inputs to the `contents` parameter:720721### Python722723 from google import genai724 from google.genai import types725726 client = genai.Client()727728 with open('dog.png', 'rb') as f:729 image_bytes = f.read()730731 result = client.models.embed_content(732 model='gemini-embedding-2',733 contents=[734 "An image of a dog",735 types.Part.from_bytes(736 data=image_bytes,737 mime_type='image/png',738 ),739 ]740 )741742 # This produces one embedding743 for embedding in result.embeddings:744 print(embedding.values)745746### JavaScript747748 import { GoogleGenAI } from "@google/genai";749 import * as fs from "node:fs";750751 async function main() {752 const ai = new GoogleGenAI({});753754 const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });755756 const response = await ai.models.embedContent({757 model: 'gemini-embedding-2',758 contents: [759 'An image of a dog',760 {761 inlineData: {762 mimeType: 'image/png',763 data: imgBase64,764 },765 },766 ],767 });768769 // This produces one embedding770 for (const embedding of response.embeddings) {771 console.log(embedding.values);772 }773 }774775 main();776777### Java778779 import com.google.genai.Client;780 import com.google.genai.types.Content;781 import com.google.genai.types.ContentEmbedding;782 import com.google.genai.types.EmbedContentResponse;783 import com.google.genai.types.Part;784 import java.nio.file.Files;785 import java.nio.file.Paths;786 import java.util.Collections;787788 Client client = new Client();789790 byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));791792 Content content =793 Content.fromParts(794 Part.fromText("An image of a dog"),795 Part.fromBytes(imageBytes, "image/png"));796797 EmbedContentResponse response =798 client.models.embedContent("gemini-embedding-2", content, null);799800 // This produces one embedding801 for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {802 System.out.println(embedding.values().orElse(Collections.emptyList()));803 }804805### REST806807 IMG_PATH="/path/to/your/dog.png"808 IMG_BASE64=$(base64 -w0 "${IMG_PATH}")809810 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \811 -H "Content-Type: application/json" \812 -H "x-goog-api-key: ${GEMINI_API_KEY}" \813 -d '{814 "content": {815 "parts": [816 {"text": "An image of a dog"},817 {818 "inline_data": {819 "mime_type": "image/png",820 "data": "'"${IMG_BASE64}"'"821 }822 }823 ]824 }825 }'826827> [!NOTE]828> **Note:** The text portion of the multimodal input shouldn't include task type information.829830On the other hand, if you use `Content` objects inside the `contents` parameter,831it returns separate embeddings. This example creates multiple embeddings in one832embedding call:833834### Python835836 from google import genai837 from google.genai import types838839 client = genai.Client()840841 with open('dog.png', 'rb') as f:842 image_bytes = f.read()843844 result = client.models.embed_content(845 model="gemini-embedding-2",846 contents=[847 types.Content(parts=[types.Part.from_text(text="task: classification | query: An image of a dog")]),848 types.Content(849 parts=[850 types.Part.from_bytes(851 data=image_bytes,852 mime_type="image/png",853 ),854 ]855 ),856 ],857 )858859 # This produces two embeddings860 for embedding in result.embeddings:861 print(embedding.values)862863### JavaScript864865 import { GoogleGenAI } from "@google/genai";866 import * as fs from "node:fs";867868 async function main() {869 const ai = new GoogleGenAI({});870871 const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });872873 const response = await ai.models.embedContent({874 model: 'gemini-embedding-2',875 contents: [876 { parts: [{ text: 'task: classification | query: An image of a dog' }] },877 {878 parts: [{879 inlineData: {880 mimeType: 'image/png',881 data: imgBase64,882 },883 }],884 },885 ],886 });887888 // This produces two embeddings889 for (const embedding of response.embeddings) {890 console.log(embedding.values);891 }892 }893894 main();895896### Java897898 import java.util.Arrays;899 import com.google.genai.Client;900 import com.google.genai.types.Content;901 import com.google.genai.types.ContentEmbedding;902 import com.google.genai.types.EmbedContentResponse;903 import com.google.genai.types.Part;904 import java.nio.file.Files;905 import java.nio.file.Paths;906 import java.util.Collections;907 import java.util.List;908909 Client client = new Client();910911 byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));912913 List<Content> contents =914 Arrays.asList(915 Content.fromParts(Part.fromText("task: classification | query: An image of a dog")),916 Content.fromParts(Part.fromBytes(imageBytes, "image/png")));917918 // Embed each Content object separately to produce separate embeddings919 for (Content content : contents) {920 EmbedContentResponse response =921 client.models.embedContent("gemini-embedding-2", content, null);922 for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {923 System.out.println(embedding.values().orElse(Collections.emptyList()));924 }925 }926927### REST928929 IMG_PATH="/path/to/your/dog.png"930 IMG_BASE64=$(base64 -w0 "${IMG_PATH}")931932 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:batchEmbedContents" \933 -H "Content-Type: application/json" \934 -H "x-goog-api-key: ${GEMINI_API_KEY}" \935 -d '{936 "requests": [937 {938 "model": "models/gemini-embedding-2",939 "content": {"parts": [{"text": "task: classification | query: An image of a dog"}]}940 },941 {942 "model": "models/gemini-embedding-2",943 "content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_BASE64}"'"}}]}944 }945 ]946 }'947948### Embedding audio949950The following example shows how to embed an audio file using951`gemini-embedding-2`.952953Audio files can be provided as inline data or as uploaded files954through the [Files API](https://ai.google.dev/gemini-api/docs/files).955956### Python957958 from google import genai959 from google.genai import types960961 with open('example.mp3', 'rb') as f:962 audio_bytes = f.read()963964 client = genai.Client()965966 result = client.models.embed_content(967 model='gemini-embedding-2',968 contents=[969 types.Part.from_bytes(970 data=audio_bytes,971 mime_type='audio/mpeg',972 ),973 ]974 )975976 print(result.embeddings)977978### JavaScript979980 import { GoogleGenAI } from "@google/genai";981 import * as fs from "node:fs";982983 async function main() {984 const ai = new GoogleGenAI({});985986 const audioBase64 = fs.readFileSync("example.mp3", { encoding: "base64" });987988 const response = await ai.models.embedContent({989 model: 'gemini-embedding-2',990 contents: [{991 inlineData: {992 mimeType: 'audio/mpeg',993 data: audioBase64,994 },995 }],996 });997998 console.log(response.embeddings);999 }10001001 main();10021003### Java10041005 import com.google.genai.Client;1006 import com.google.genai.types.Content;1007 import com.google.genai.types.EmbedContentResponse;1008 import com.google.genai.types.Part;1009 import java.nio.file.Files;1010 import java.nio.file.Paths;10111012 Client client = new Client();10131014 byte[] audioBytes = Files.readAllBytes(Paths.get("example.mp3"));10151016 Content content = Content.fromParts(Part.fromBytes(audioBytes, "audio/mpeg"));10171018 EmbedContentResponse response =1019 client.models.embedContent("gemini-embedding-2", content, null);10201021 System.out.println(response.embeddings().orElse(null));10221023### REST10241025 AUDIO_PATH="/path/to/your/example.mp3"1026 AUDIO_BASE64=$(base64 -w0 "${AUDIO_PATH}")10271028 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \1029 -H "Content-Type: application/json" \1030 -H "x-goog-api-key: ${GEMINI_API_KEY}" \1031 -d '{1032 "content": {1033 "parts": [{1034 "inline_data": {1035 "mime_type": "audio/mpeg",1036 "data": "'"${AUDIO_BASE64}"'"1037 }1038 }]1039 }1040 }'10411042### Embedding video10431044The following example shows how to embed a video using1045`gemini-embedding-2`.10461047Videos can be provided as inline data or as uploaded files1048through the [Files API](https://ai.google.dev/gemini-api/docs/files).10491050### Python10511052 from google import genai1053 from google.genai import types10541055 client = genai.Client()10561057 with open('example.mp4', 'rb') as f:1058 video_bytes = f.read()10591060 result = client.models.embed_content(1061 model='gemini-embedding-2',1062 contents=[1063 types.Part.from_bytes(1064 data=video_bytes,1065 mime_type='video/mp4',1066 ),1067 ]1068 )10691070 print(result.embeddings[0].values)10711072### JavaScript10731074 import { GoogleGenAI } from "@google/genai";1075 import * as fs from "node:fs";10761077 async function main() {1078 const ai = new GoogleGenAI({});10791080 const videoBase64 = fs.readFileSync("example.mp4", { encoding: "base64" });10811082 const response = await ai.models.embedContent({1083 model: 'gemini-embedding-2',1084 contents: [{1085 inlineData: {1086 mimeType: 'video/mp4',1087 data: videoBase64,1088 },1089 }],1090 });10911092 console.log(response.embeddings);1093 }10941095 main();10961097### Java10981099 import com.google.genai.Client;1100 import com.google.genai.types.Content;1101 import com.google.genai.types.EmbedContentResponse;1102 import com.google.genai.types.Part;1103 import java.nio.file.Files;1104 import java.nio.file.Paths;1105 import java.util.Collections;11061107 Client client = new Client();11081109 byte[] videoBytes = Files.readAllBytes(Paths.get("example.mp4"));11101111 Content content = Content.fromParts(Part.fromBytes(videoBytes, "video/mp4"));11121113 EmbedContentResponse response =1114 client.models.embedContent("gemini-embedding-2", content, null);11151116 System.out.println(1117 response.embeddings().get().get(0).values().orElse(Collections.emptyList()));11181119### REST11201121 VIDEO_PATH="/path/to/your/video.mp4"1122 VIDEO_BASE64=$(base64 -w0 "${VIDEO_PATH}")11231124 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \1125 -H "Content-Type: application/json" \1126 -H "x-goog-api-key: ${GEMINI_API_KEY}" \1127 -d '{1128 "content": {1129 "parts": [{1130 "inline_data": {1131 "mime_type": "video/mp4",1132 "data": "'"${VIDEO_BASE64}"'"1133 }1134 }]1135 }1136 }'11371138If you need to embed videos \>120 seconds, you can chunk the video into1139overlapping segments and embed those chunks individually.11401141### Embedding documents11421143Documents in PDF format can be embedded directly. The model processes the visual and text1144content of each page.11451146PDFs can be provided as inline data or as uploaded files1147through the [Files API](https://ai.google.dev/gemini-api/docs/files).11481149#### How the model processes PDFs11501151When you embed a PDF, the model processes the document using both visual and text features:11521153- **Visual representation:** The model renders each page as an image, which consumes **258 tokens** per page.1154- **Text extraction:** The model extracts text from the document. For **native PDFs** (which contain digital text), the model extracts the text directly. For **scanned PDFs** (which contain images of text), the model automatically runs optical character recognition (OCR) to extract the text.11551156To calculate the total token count for a PDF, add the visual tokens (258 per page) to the text tokens. Your inputs must fit within the model's **8,192 token limit** (shared across all modalities). The system silently truncates inputs that exceed this limit.11571158> [!NOTE]1159> **Note:** The Gemini Developer API always enables OCR for PDFs and does not support disabling it (the `document_ocr` parameter is only available in Vertex AI).11601161#### PDF limits11621163- **Files per request:** You can submit a maximum of 1 PDF file.1164- **Page limit:** You can submit a maximum of 6 pages per file. For the best quality, we strongly recommend using 1 page per PDF.11651166The following example shows how to embed a PDF using `gemini-embedding-2`:11671168### Python11691170 from google import genai1171 from google.genai import types11721173 with open('example.pdf', 'rb') as f:1174 pdf_bytes = f.read()11751176 client = genai.Client()11771178 result = client.models.embed_content(1179 model='gemini-embedding-2',1180 contents=[1181 types.Part.from_bytes(1182 data=pdf_bytes,1183 mime_type='application/pdf',1184 ),1185 ]1186 )11871188 print(result.embeddings)11891190### JavaScript11911192 import { GoogleGenAI } from "@google/genai";1193 import * as fs from "node:fs";11941195 async function main() {1196 const ai = new GoogleGenAI({});11971198 const pdfBase64 = fs.readFileSync("example.pdf", { encoding: "base64" });11991200 const response = await ai.models.embedContent({1201 model: 'gemini-embedding-2',1202 contents: [{1203 inlineData: {1204 mimeType: 'application/pdf',1205 data: pdfBase64,1206 },1207 }],1208 });12091210 console.log(response.embeddings);1211 }12121213 main();12141215### Java12161217 import com.google.genai.Client;1218 import com.google.genai.types.Content;1219 import com.google.genai.types.EmbedContentResponse;1220 import com.google.genai.types.Part;1221 import java.nio.file.Files;1222 import java.nio.file.Paths;12231224 Client client = new Client();12251226 byte[] pdfBytes = Files.readAllBytes(Paths.get("example.pdf"));12271228 Content content = Content.fromParts(Part.fromBytes(pdfBytes, "application/pdf"));12291230 EmbedContentResponse response =1231 client.models.embedContent("gemini-embedding-2", content, null);12321233 System.out.println(response.embeddings().orElse(null));12341235### REST12361237 PDF_PATH="/path/to/your/example.pdf"1238 PDF_BASE64=$(base64 -w0 "${PDF_PATH}")12391240 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \1241 -H "Content-Type: application/json" \1242 -H "x-goog-api-key: ${GEMINI_API_KEY}" \1243 -d '{1244 "content": {1245 "parts": [{1246 "inline_data": {1247 "mime_type": "application/pdf",1248 "data": "'"${PDF_BASE64}"'"1249 }1250 }]1251 }1252 }'12531254## Use cases12551256Text embeddings are crucial for a variety of common AI use cases, such as:12571258- **Retrieval-Augmented Generation (RAG):** Embeddings enhance the quality of generated text by retrieving and incorporating relevant information into the context of a model.1259- **Information retrieval:** Search for the most semantically similar text or1260 documents given a piece of input text.12611262 [Document search tutorial](https://github.com/google-gemini/cookbook/blob/main/examples/Talk_to_documents_with_embeddings.ipynb)1263- **Search reranking**: Prioritize the most relevant items by semantically1264 scoring initial results against the query.12651266 [Search reranking tutorial](https://github.com/google-gemini/cookbook/blob/main/examples/Search_reranking_using_embeddings.ipynb)1267- **Anomaly detection:** Comparing groups of embeddings can help identify1268 hidden trends or outliers.12691270 [Anomaly detection tutorial](https://github.com/google-gemini/cookbook/blob/main/examples/Anomaly_detection_with_embeddings.ipynb)1271- **Classification:** Automatically categorize text based on its content, such1272 as sentiment analysis or spam detection12731274 [Classification tutorial](https://github.com/google-gemini/cookbook/blob/main/examples/Classify_text_with_embeddings.ipynb)1275- **Clustering:** Effectively grasp complex relationships by creating clusters1276 and visualizations of your embeddings.12771278 [Clustering visualization tutorial](https://github.com/google-gemini/cookbook/blob/main/examples/clustering_with_embeddings.ipynb)12791280## Storing embeddings12811282As you take embeddings to production, it is common to1283use **vector databases** to efficiently store, index, and retrieve1284high-dimensional embeddings. Google Cloud offers managed data services that1285can be used for this purpose including1286[Gemini Enterprise Agent Platform Vector Search 2.0](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/vector-search-2/overview),1287[BigQuery](https://cloud.google.com/bigquery/docs/introduction),1288[AlloyDB](https://cloud.google.com/alloydb/docs/overview), and1289[Cloud SQL](https://cloud.google.com/sql/docs/postgres/introduction).12901291The following tutorials show how to use other third party vector databases1292with Gemini Embedding.12931294- [ChromaDB tutorials](https://docs.trychroma.com/integrations/embedding-models/google-gemini)1295- [QDrant tutorials](https://qdrant.tech/documentation/embeddings/gemini/)1296- [Weaviate tutorials](https://docs.weaviate.io/weaviate/model-providers/google)1297- [Pinecone tutorials](https://github.com/google-gemini/cookbook/blob/main/examples/langchain/Gemini_LangChain_QA_Pinecone_WebLoad.ipynb)12981299## Model versions13001301### Gemini Embedding 213021303| Property | Description |1304|---|---|1305| Model code | **Gemini API** `gemini-embedding-2` |1306| Supported data types | **Input** Text, image, video, audio, PDF **Output** Text embeddings |1307| Token limits^[\[\*\]](https://ai.google.dev/gemini-api/docs/tokens)^ | **Input token limit** 8,192 **Output dimension size** Flexible, supports: 128 - 3072, Recommended: 768, 1536, 3072 |1308| Versions | Read the [model version patterns](https://ai.google.dev/gemini-api/docs/models/gemini#model-versions) for more details. - Stable: `gemini-embedding-2` |1309| Latest update | April 2026 |13101311### Gemini Embedding13121313| Property | Description |1314|---|---|1315| Model code | **Gemini API** `gemini-embedding-001` |1316| Supported data types | **Input** Text **Output** Text embeddings |1317| Token limits^[\[\*\]](https://ai.google.dev/gemini-api/docs/tokens)^ | **Input token limit** 2,048 **Output dimension size** Flexible, supports: 128 - 3072, Recommended: 768, 1536, 3072 |1318| Versions | Read the [model version patterns](https://ai.google.dev/gemini-api/docs/models/gemini#model-versions) for more details. - Stable: `gemini-embedding-001` |1319| Latest update | June 2025 |13201321For deprecated Embeddings models, visit the [Deprecations](https://ai.google.dev/gemini-api/docs/deprecations) page13221323## Migration from gemini-embedding-00113241325The embedding spaces between `gemini-embedding-001` and1326`gemini-embedding-2` are **incompatible** . This means you cannot1327directly compare embeddings generated by one model with embeddings generated by1328the other. If you are upgrading to `gemini-embedding-2`, you must1329re-embed all of your existing data.13301331Beyond incompatibility, there are several other notable differences between1332the two models:13331334- **Task type specification:** With `gemini-embedding-001`, you specify the1335 task type using the `task_type` parameter (e.g., `SEMANTIC_SIMILARITY`,1336 `RETRIEVAL_DOCUMENT`). With `gemini-embedding-2`, the `task_type`1337 parameter is not supported. Instead, you should include task instructions1338 directly in the prompt for text-only tasks. See1339 [Task types with Embeddings 2](https://ai.google.dev/gemini-api/docs/embeddings#task-types-embeddings-2) for details on how1340 to format prompts for different use cases.13411342- **Embedding aggregation:** `gemini-embedding-001` generates individual1343 embeddings for each string in a list of inputs. In contrast,1344 `gemini-embedding-2` produces a single, aggregated embedding when multiple1345 inputs (like text and images) are provided directly in one request. To1346 generate separate embeddings for individual inputs, wrap each input in a1347 `Content` object, or use the1348 [Batch API](https://ai.google.dev/gemini-api/docs/batch-api#batch-embedding). See1349 [Embedding aggregation](https://ai.google.dev/gemini-api/docs/embeddings#embedding-aggregation) for more information.13501351- **Normalization:** If you use `output_dimensionality` to request embeddings1352 with fewer than 3072 dimensions, `gemini-embedding-2` automatically1353 normalizes these truncated embeddings. With `gemini-embedding-001`, you1354 need to perform manual normalization for dimensions other than 3072. See1355 [Ensuring quality for smaller dimensions](https://ai.google.dev/gemini-api/docs/embeddings#quality-for-smaller-dimensions)1356 for details.13571358## Batch embeddings13591360If latency is not a concern, try using the Gemini Embeddings models with1361[Batch API](https://ai.google.dev/gemini-api/docs/batch-api#batch-embedding). This1362allows for much higher throughput at 50% of the default Embedding price.1363Find examples on how to get started in the [Batch API cookbook](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb).13641365## Responsible use notice13661367Unlike generative AI models that create new content, the Gemini Embedding model1368is only intended to transform the format of your input data into a numerical1369representation. While Google is responsible for providing an embedding model1370that transforms the format of your input data to the numerical-format requested,1371users retain full responsibility for the data they input and the resulting1372embeddings. By using the Gemini Embedding model you confirm that you have the1373necessary rights to any content that you upload. Do not generate content that1374infringes on others' intellectual property or privacy rights. Your use of this1375service is subject to our [Prohibited Use1376Policy](https://policies.google.com/terms/generative-ai/use-policy) and1377[Google's Terms of Service](https://ai.google.dev/gemini-api/terms).13781379## Start building with embeddings13801381Check out the [embeddings quickstart1382notebook](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Embeddings.ipynb)1383to explore the model capabilities and learn how to customize and visualize your1384embeddings.