Gemini Embedding 2 API

Model overview

Gemini Embedding 2 is Google's multimodal embedding model. It maps text, images, PDFs, audio, and video into a shared semantic space for semantic search, cross-modal retrieval, classification, and RAG knowledge bases. It returns numeric vectors for similarity calculations and indexing.

Property	Description
Model name	gemini-embedding-2
Inputs	Text, images, PDFs, audio, and video, including combined inputs
Context window	Up to 8,192 tokens across all inputs
Output dimensions	3,072 by default; adjust with embedContentConfig.outputDimensionality, for example 768 or 1536

See the official model documentation for media formats, counts, and duration limits.

API usage

Endpoint and authentication

Use Google's native embedContent interface with the Exchange Token endpoint and your platform API key:

POST https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent

Content-Type: application/json
x-goog-api-key: YOUR_API_KEY

You can also replace x-goog-api-key with Authorization: Bearer YOUR_API_KEY.

Requests and responses on this page follow the Google Cloud native embedContent REST schema.

Request Body

Field	Type	Required	Description
content	object	Yes	Input to embed
content.parts	array	Yes	Input parts; each uses one of text, inlineData, or fileData
content.parts[].text	string	By input type	Text input
content.parts[].inlineData	object	By input type	Media with mimeType and Base64 data, without a data:...;base64, prefix
content.parts[].fileData	object	By input type	File with mimeType and an upstream-readable fileUri, such as gs://...
embedContentConfig	object	No	Embedding options
embedContentConfig.outputDimensionality	integer	No	Vector dimensions
embedContentConfig.documentOcr	boolean	No	Enable document OCR
embedContentConfig.audioTrackExtraction	boolean	No	Include a video's audio track

All parts in one content.parts produce one vector. Text and an image together produce a joint representation; send two requests to index them separately.

For text retrieval, put instructions in the text, such as task: search result | query: How can I track my order?. Format documents as title: Order help | text: Track delivery on the orders page. This model uses text instructions instead of the older taskType / task_type parameter. See the official task instructions.

Response Body

A successful call returns a JSON object:

Field	Type	Description
embedding.values	number[]	Generated vector
usageMetadata.promptTokenCount	integer	Input tokens
usageMetadata.totalTokenCount	integer	Total tokens, when returned
usageMetadata.promptTokensDetails	array	Input usage by modality
usageMetadata.promptTokensDetails[].modality	string	For example, TEXT, IMAGE, AUDIO, or VIDEO
usageMetadata.promptTokensDetails[].tokenCount	integer	Tokens for that modality
truncated	boolean	Whether input was truncated, when returned

This illustrative response shows only the first 3 vector values and uses sample usage counts. Actual dimensions and usage come from your response.

{
  "embedding": {
    "values": [0.012345, -0.023456, 0.034567]
  },
  "usageMetadata": {
    "promptTokenCount": 12,
    "totalTokenCount": 12,
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 12 }
    ]
  },
  "truncated": false
}

Read the vector from embedding.values. This endpoint returns a single embedding object.

Examples

Set your Exchange Token API key. All examples below use this environment variable:

export EXCHANGE_TOKEN_API_KEY="YOUR_API_KEY"

Text embedding (cURL)

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{ "text": "Exchange Token provides unified access to model APIs." }]
    }
  }'

Retrieval query with custom dimensions (cURL)

Generate a 768-dimensional query vector. Index documents with the same model and dimensions, replacing the text with the document content and task format.

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{ "text": "task: search result | query: How can I track my order?" }]
    },
    "embedContentConfig": {
      "outputDimensionality": 768
    }
  }'

Joint text and image embedding (Python)

Encode a local image.png as Base64 and embed it together with text. This example uses only the Python standard library.

import base64
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

image_data = base64.b64encode(Path("image.png").read_bytes()).decode("ascii")
payload = {
    "content": {
        "parts": [
            {"text": "A dog running across a grassy field"},
            {"inlineData": {"mimeType": "image/png", "data": image_data}},
        ]
    },
    "embedContentConfig": {"outputDimensionality": 768},
}

request = Request(
    "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "x-goog-api-key": os.environ["EXCHANGE_TOKEN_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=120) as response:
    result = json.load(response)

values = result["embedding"]["values"]
print("Dimensions:", len(values))
print("First 5 values:", values[:5])
print("Usage:", result.get("usageMetadata"))

You can also send PDFs, audio, and video through inlineData. Replace the file, mimeType, and optional text. Remove the text Part to embed only the file. Common types are listed below; files must meet the model limits.

Input	Example MIME types
Image	image/png, image/jpeg
PDF	application/pdf
Audio	audio/mp3, audio/wav
Video	video/mp4, video/mpeg

Reference a PDF file (cURL)

Use fileData for an existing Google Cloud Storage file that upstream can read. Replace gs://YOUR_BUCKET/document.pdf with your URI and ensure upstream has read access; a URI does not upload a local file. This example enables document OCR.

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{
        "fileData": {
          "mimeType": "application/pdf",
          "fileUri": "gs://YOUR_BUCKET/document.pdf"
        }
      }]
    },
    "embedContentConfig": {
      "outputDimensionality": 768,
      "documentOcr": true
    }
  }'