> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Gemini embeddings

> Create native single and batch embeddings and validate vectors.

At revision `30a6d88a4`, `controller/relay.go` dispatches native embeddings with case-sensitive `strings.Contains(path, "embed")`. The action `:batchEmbedContents` contains no lowercase `embed`, so the path model ID must contain lowercase `embed`, such as an available embedding model name. Other aliases can enter the wrong handler. The example rejects such batch aliases before sending. This is a current gateway limitation, not a Gemini protocol requirement; review it after upgrading.

Native Gemini `:embedContent` and synchronous `:batchEmbedContents` accept `content.parts` and return `embedding.values` / `embeddings[].values`. These differ from [OpenAI Embeddings](/en/guides/embeddings) `input` / `data[].embedding`. The batch action is not the asynchronous Batch API.

Follow [REST runtime](/en/guides/http-runtime), use a bare model ID without `models/`, and select a channel supporting native Gemini embeddings.

```bash theme={null}
node examples/gemini-embeddings.mjs single
node examples/gemini-embeddings.mjs batch
```

All entries use one model. The gateway maps the path model upstream and rewrites each entry's `model`; do not mix models within a batch. The typed request preserves `model`, `content`, `taskType`, `title`, and `outputDimensionality`. Do not assume unknown top-level fields survive.

The example encodes documents with `RETRIEVAL_DOCUMENT`; queries generally use the corresponding `RETRIEVAL_QUERY`. Confirm these options with the model. `title` applies to document retrieval; dimensionality limits and task types depend on the model. The example checks count, finite nonempty numeric vectors, and consistent dimensions before printing. It does not assume normalization or compare vectors across models.

See [single API](/en/api-reference/gemini-embed), [batch API](/en/api-reference/gemini-batch-embed), and the [Google protocol reference](https://ai.google.dev/api/embeddings). Verify model capabilities and limits in your deployment.

```javascript theme={null}
import { requestJSON } from './http-client.mjs';

try {
  const model = process.env.API_MODEL;
  const mode = process.argv[2] || 'single';
  if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(model || '') || !['single', 'batch'].includes(mode)) {
    throw new Error('Set a bare API_MODEL and use single or batch.');
  }
  // Current gateway dispatch uses a case-sensitive "embed" path check.
  if (mode === 'batch' && !model.includes('embed')) throw new Error('Batch requires an embedding model ID containing lowercase embed on this gateway revision.');
  const texts = mode === 'single' ? ['A guide to API integration.']
    : ['A guide to API integration.', 'A guide to vector retrieval.'];
  const inputs = texts.map((text) => ({
    model: `models/${model}`, content: { parts: [{ text }] }, taskType: 'RETRIEVAL_DOCUMENT',
  }));
  const action = mode === 'single' ? 'embedContent' : 'batchEmbedContents';
  const result = await requestJSON(`/v1beta/models/${encodeURIComponent(model)}:${action}`,
    mode === 'single' ? inputs[0] : { requests: inputs });
  const vectors = mode === 'single' ? [result.embedding] : result.embeddings;
  if (!Array.isArray(vectors) || vectors.length !== texts.length) throw new Error('Missing vectors.');
  let dimensions;
  for (const vector of vectors) {
    const values = vector?.values;
    if (!Array.isArray(values) || !values.length || !values.every((value) => typeof value === 'number' && Number.isFinite(value))
      || (dimensions !== undefined && dimensions !== values.length)) throw new Error('Invalid vector.');
    dimensions = values.length;
  }
  console.log(JSON.stringify({ count: vectors.length, dimensions, vectors: vectors.map((item) => item.values) }));
} catch {
  console.error('Gemini embedding request failed or returned invalid vectors. No automatic retry.');
  process.exitCode = 1;
}
```

[阅读中文版](/zh/guides/gemini-embeddings)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.