> ## Documentation Index
> Fetch the complete documentation index at: https://docs.znapai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gemini Embedding
## Request
```shellscript cURL theme={null}
curl "https://api.znapai.com/gemini/v1beta/models/gemini-embedding-2:embedContent" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": {
"parts": [{"text": "What is the meaning of life?"}]
}
}'
```
## Response
```json theme={null}
{
"embedding": {
"values": [
0.01234567,
-0.09876543,
0.0054321
]
}
}
```
***
## Parameters
The content to be embedded. Contains an ordered list of parts.
An ordered list of parts that constitute the content.
The text prompt or content to embed.
Inline media data (e.g., images, video, audio) for multimodal embeddings.
The MIME type of the media data (e.g., `image/png`, `audio/mpeg`, `video/mp4`, `application/pdf`).
Base64 encoded media data.
The maximum number of dimensions to include in the output embedding. Truncates the output vector. Recommended values: `768`, `1536`, `3072`.
Only supported on `gemini-embedding-001` (legacy). Specifies the task type.
Options:
* `SEMANTIC_SIMILARITY`: Text similarity — recommendation, duplicate detection
* `CLASSIFICATION`: Sentiment analysis, spam detection
* `CLUSTERING`: Document organization, market research, anomaly detection
* `RETRIEVAL_DOCUMENT`: Documents to be indexed/retrieved
* `RETRIEVAL_QUERY`: Search queries (pair with `RETRIEVAL_DOCUMENT` for the docs)
* `CODE_RETRIEVAL_QUERY`: Natural-language code search queries
* `QUESTION_ANSWERING`: Questions in a QA system
* `FACT_VERIFICATION`: Statements to verify against retrieved evidence
***
## Usage examples
### Alternative Route Prefix
You can also use the `/v1beta/` route prefix instead of `/gemini/v1beta/`:
```shellscript cURL theme={null}
curl "https://api.znapai.com/v1beta/models/gemini-embedding-2:embedContent" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": {"parts": [{"text": "What is the meaning of life?"}]}}'
```
> \[!NOTE]
> You can also authenticate using the `?key=$ZnapAI_API_KEY` query parameter instead of the header if required by your integration. Both prefix routes support both auth styles.
### Multimodal embeddings (`gemini-embedding-2` only)
All modalities map into the same embedding space. Example passing base64 image data:
```shellscript cURL theme={null}
IMG_BASE64=$(base64 -w0 "/path/to/image.png")
curl "https://api.znapai.com/gemini/v1beta/models/gemini-embedding-2:embedContent" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": {
"parts": [{
"inline_data": {
"mime_type": "image/png",
"data": "'"${IMG_BASE64}"'"
}
}]
}
}'
```
#### Supported modalities and limits
| Modality | Specifications and limits |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Text | Up to 8,192 tokens |
| Image | Max 6 images per request. PNG, JPEG |
| Audio | Max 180s. MP3, WAV |
| Video | Max 120s. MP4, MOV (H264, H265, AV1, VP9). Sampled at 1 fps (≤32s) or uniformly to 32 frames (longer). No audio track processed |
| Documents (PDF) | Max 1 file per request, up to 6 pages |
### Batch embeddings (`batchEmbedContents`)
Returns separate embeddings for multiple inputs in a single API call:
```shellscript cURL theme={null}
curl "https://api.znapai.com/gemini/v1beta/models/gemini-embedding-2:batchEmbedContents" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"requests": [
{
"model": "models/gemini-embedding-2",
"content": {"parts": [{"text": "An image of a dog"}]}
},
{
"model": "models/gemini-embedding-2",
"content": {"parts": [{"text": "A cat on a mat"}]}
}
]
}'
```
### Specify task type to improve performance
#### Task types with Embeddings 2 (`gemini-embedding-2`)
`gemini-embedding-2` does **not** accept a `task_type` field. Instead, prefix the task instruction directly into the text you embed.
**Retrieval use cases (asymmetric format)**
| Use case | Query structure | Document structure |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------- |
| Search query | `task: search result \| query: {content}` | `title: {title} \| text: {content}` (use `title: none` if no title) |
| Question answering | `task: question answering \| query: {content}` | `title: {title} \| text: {content}` |
| Fact checking | `task: fact checking \| query: {content}` | `title: {title} \| text: {content}` |
| Code retrieval | `task: code retrieval \| query: {content}` | `title: {title} \| text: {content}` |
**Single-input use cases (symmetric format)** — use the same prefix for query and document.
| Use case | Input structure |
| ------------------- | ----------------------------------------------- |
| Classification | `task: classification \| query: {content}` |
| Clustering | `task: clustering \| query: {content}` |
| Semantic similarity | `task: sentence similarity \| query: {content}` |
Example structure query:
```shellscript cURL theme={null}
curl "https://api.znapai.com/gemini/v1beta/models/gemini-embedding-2:embedContent" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": {"parts": [{"text": "task: search result | query: what is the meaning of life"}]}}'
```
#### Task types with Embeddings 001 (`gemini-embedding-001`)
For `gemini-embedding-001`, pass the `taskType` in the request body:
```shellscript cURL theme={null}
curl "https://api.znapai.com/gemini/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $ZnapAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taskType": "SEMANTIC_SIMILARITY",
"content": {"parts": [{"text": "What is the meaning of life?"}]}
}'
```
### Controlling embedding size
`output_dimensionality` truncates the output vector. Both models default to 3072 dimensions. Recommended values: `768`, `1536`, `3072`.
> \[!NOTE]
> `gemini-embedding-2` auto-normalizes truncated dimensions (e.g. 768, 1536) so cosine similarity works correctly out of the box. `gemini-embedding-001` requires you to manually L2-normalize non-3072-dim vectors client-side.
```json theme={null}
{
"usage_object": {
"total_tokens": 3,
"prompt_tokens": 3,
"completion_tokens": 0
},
"cost_breakdown": {
"input_cost": 6e-7,
"output_cost": 0,
"original_cost": 6e-7,
"total_cost": 3.6e-7
}
}
```
***
## Params to Avoid
| Param | Reason |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `model` (top-level body field) | Model is specified in the URL path; a body `model` field is forwarded but ignored for routing |
| `task_type` / `taskType` | Only valid for `gemini-embedding-001`; rejected by `gemini-embedding-2` — use prompt-prefix instructions instead |
| `spend-logs-metadata` in JSON body | Must be passed as an HTTP header (`spend-logs-metadata`), not a body field |
***
## Model versions
### Gemini Embedding 2
| Property | Description |
| --------------------- | ------------------------------------------------ |
| Model code | `gemini-embedding-2` |
| Input | Text, image, video, audio, PDF |
| Output | Text embeddings |
| Input token limit | 8,192 |
| Output dimension size | Flexible: 128–3072. Recommended: 768, 1536, 3072 |
### Gemini Embedding 001
| Property | Description |
| --------------------- | ------------------------------------------------ |
| Model code | `gemini-embedding-001` |
| Input | Text only |
| Output | Text embeddings |
| Input token limit | 2,048 |
| Output dimension size | Flexible: 128–3072. Recommended: 768, 1536, 3072 |
***