# 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) | automatic | Apr 2026 |

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`

```json
{"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`.