Gemini embeddings — embedContent, batchEmbedContents, asyncBatchEmbedContent
Status: DOCUMENTED + LIVE_VERIFIED (gemini-embedding-001, gemini-embedding-2; 12 probes, 2026-09-18). asyncBatchEmbedContent → ACCOUNT_RESTRICTED (400 FAILED_PRECONDITION on the free tier).
Sources: https://ai.google.dev/gemini-api/docs/embeddings · https://ai.google.dev/api/embeddings · https://ai.google.dev/gemini-api/docs/pricing#gemini-embedding-2 · discovery EmbedContentRequest, EmbedContentConfig, EmbedContentBatch
Machine-readable: generated/fragments/parameters/gemini-embeddings.json, generated/fragments/endpoints/gemini-core.json, generated/fragments/objects/gemini-core-objects.json#EmbedContentResponse|BatchEmbedContentsResponse|EmbedContentBatch, matrix rows gemini-embedding-*
Last verified: 2026-09-18
1. Models
| Model | Input | Input limit | Output dims | Task type | Normalization of truncated vectors | Latest update |
|---|---|---|---|---|---|---|
gemini-embedding-001 |
text | 2,048 tokens | 3072 default; 128–3072 (recommended 768/1536/3072) | taskType param (8 values) |
manual | Jun 2025 |
gemini-embedding-2 (+ -preview) |
text, image (≤6 PNG/JPEG), audio (≤180 s MP3/WAV), video (≤120 s MP4/MOV, 32 frames, no audio track), PDF (1 file ≤6 pages, 258 tokens/page + text) | 8,192 tokens (shared) | same | not supported — put `task: search result | query: …/title: … |
text: …prefixes in the text (live:taskType` was accepted silently) |
Embedding spaces of 001 and 2 are incompatible — re-embed when migrating. Generation models → 404 … not supported for embedContent.
2. POST /v1beta/models/{model}:embedContent
{"content": {"parts": [{"text": "task: classification | query: Hello world"}]}, "outputDimensionality": 64}| Field | Notes |
|---|---|
content (required) |
one Content; embedding-2 aggregates all parts into one vector (text + PNG → 1 vector, usage TEXT 3 + IMAGE 258). |
outputDimensionality |
truncation (MRL). Live: 64 → 64 floats on both models (below the documented 128 floor); default → 3072; 4096 → 400 Unable to submit request because the outputDimensionality value is not supported. |
taskType |
RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION, CODE_RETRIEVAL_QUERY (001). |
title |
only with RETRIEVAL_DOCUMENT (001). |
embedContentConfig |
nested equivalent {taskType, title, outputDimensionality, autoTruncate, documentOcr, audioTrackExtraction} — verified {outputDimensionality: 64, autoTruncate: true}. Top-level taskType/title/outputDimensionality are marked deprecated in discovery. |
model (body) |
optional models/{id} echo (required inside batch requests). |
Response: {"embedding": {"values": [...]}, "usageMetadata": {"promptTokenCount", "promptTokenDetails": [{modality, tokenCount}]}} — usageMetadata returned by embedding-2 only (001 returns just embedding).
3. POST …:batchEmbedContents (sync)
{"requests": [{"model": "models/gemini-embedding-001", "content": {...}, "outputDimensionality": 64}, ...]} → {"embeddings": [{values}, {values}]} in order. Each request must repeat model (400 * BatchEmbedContentsRequest.requests[0].model: model is not specified). The SDK's embed_content(contents=[...]) uses this. For embedding-2, separate Content objects → separate vectors; parts inside one content → one vector.
4. POST …:asyncBatchEmbedContent (Batch API, 50 % price)
Body {"batch": {"displayName", "inputConfig": {"requests": {"requests": [{"request": EmbedContentRequest, "metadata": {...}}]}} | {"fileName": "files/…"}, "priority"}} → Operation whose response is an EmbedContentBatch (state BATCH_STATE_PENDING|RUNNING|SUCCEEDED|FAILED|CANCELLED|EXPIRED, output.inlinedResponses | responsesFile, batchStats). Live on this key: 400 FAILED_PRECONDITION Precondition check failed. (requires billing). Batch lifecycle (/v1beta/batches) is documented by the batch domain.
5. Pricing (2026-09)
| Model | Text input / 1M | Image | Audio | Video | Batch |
|---|---|---|---|---|---|
| gemini-embedding-2 | $0.20 | $0.45/1M tok ($0.00012/image) | $6.50/1M ($0.00016/s) | $12.00/1M ($0.00079/frame) | 50 % |
| gemini-embedding-001 | (see pricing page, "Gemini Embedding") | — | — | — | 50 % |
MTEB (001): 3072/2048/1536 ≈ 68.2, 768 ≈ 68.0, 512 ≈ 67.6, 256 ≈ 66.2, 128 ≈ 63.3.
6. Legacy
embedText / batchEmbedText / countTextTokens (PaLM) → 404 even though countTextTokens is still listed in the embedding models' supportedGenerationMethods. See legacy-palm-methods.md.
Examples: examples/gemini/embeddings/. Tests: tests/gemini/test_embeddings.py.