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

content

object

required

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

Hide content

parts

array

required

An ordered list of parts that constitute the content.

Hide parts[]

text

string

The text prompt or content to embed.

inline_data

object

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

Show inline_data

mime_type

string

required

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

data

string

required

Base64 encoded media data.

output_dimensionality

integer

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

taskType

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