Gemini Embedding - ZnapAI Documentation

Request

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

{
  "embedding": {
    "values": [
      0.01234567,
      -0.09876543,
      0.0054321
    ]
  }
}

Parameters

object

required

The content to be embedded. Contains an ordered list of parts.

Show content

array

required

An ordered list of parts that constitute the content.

Show parts[]

string

The text prompt or content to embed.

object

Inline media data (e.g., images, video, audio) for multimodal embeddings.

Show inline_data

string

required

The MIME type of the media data (e.g., image/png, audio/mpeg, video/mp4, application/pdf).

string

required

Base64 encoded media data.

integer

The maximum number of dimensions to include in the output embedding. Truncates the output vector. Recommended values: 768, 1536, 3072.

string

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/:

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:

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:

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:

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:

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.

{
  "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

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}`

​Request

​Response

​Parameters

​Usage examples

​Alternative Route Prefix

​Multimodal embeddings (gemini-embedding-2 only)

​Supported modalities and limits

​Batch embeddings (batchEmbedContents)

​Specify task type to improve performance

​Task types with Embeddings 2 (gemini-embedding-2)

​Task types with Embeddings 001 (gemini-embedding-001)

​Controlling embedding size

​Params to Avoid

​Model versions

​Gemini Embedding 2

​Gemini Embedding 001

Request

Response

Parameters

Usage examples

Alternative Route Prefix

Multimodal embeddings (`gemini-embedding-2` only)

Supported modalities and limits

Batch embeddings (`batchEmbedContents`)

Specify task type to improve performance

Task types with Embeddings 2 (`gemini-embedding-2`)

Task types with Embeddings 001 (`gemini-embedding-001`)

Controlling embedding size

Params to Avoid

Model versions

Gemini Embedding 2

Gemini Embedding 001