Gemini Embedding 2 API

模型介绍

Gemini Embedding 2 是 Google 的多模态向量模型，可将文本、图片、PDF、音频和视频映射到同一语义空间，适用于语义搜索、跨模态检索、分类和 RAG 知识库。模型返回数值向量，用于相似度计算和向量索引。

项目	说明
模型名称	gemini-embedding-2
输入类型	文本、图片、PDF、音频、视频，可组合输入
上下文长度	所有输入合计最多 8,192 tokens
输出维度	默认 3,072 维，可通过 embedContentConfig.outputDimensionality 调整，例如 768 或 1536

各类媒体的格式、数量和时长限制见 Google 官方模型说明。

调用方式

接口与鉴权

使用 Google 原生 embedContent 接口，将调用地址替换为 Exchange Token，并使用平台 API Key：

POST https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent

Content-Type: application/json
x-goog-api-key: YOUR_API_KEY

也可以将 x-goog-api-key 替换为 Authorization: Bearer YOUR_API_KEY。

本文请求与响应采用 Google Cloud 原生 embedContent REST 定义。

Request Body

字段	类型	必填	说明
content	object	是	本次需要生成向量的内容
content.parts	array	是	输入内容列表，每个 Part 使用 text、inlineData 或 fileData 之一
content.parts[].text	string	按输入类型	文本内容
content.parts[].inlineData	object	按输入类型	内联媒体，包含 mimeType 和 Base64 编码的 data；data 不带 data:...;base64, 前缀
content.parts[].fileData	object	按输入类型	文件引用，包含 mimeType 和上游可读取的 fileUri，例如 gs://...
embedContentConfig	object	否	向量生成配置
embedContentConfig.outputDimensionality	integer	否	输出向量维度
embedContentConfig.documentOcr	boolean	否	是否对文档启用 OCR
embedContentConfig.audioTrackExtraction	boolean	否	是否提取视频音轨参与向量生成

同一个 content.parts 中的内容会共同生成一条向量。例如一段文本与一张图片会得到它们的联合表示；若要分别入库，应拆成两个请求。

文本检索任务可在文本中写入任务指令，例如 task: search result | query: 如何查询订单；待检索文档使用 title: 订单帮助 | text: 在订单页面查看物流进度。。该模型通过文本指令指定任务，不使用旧模型的 taskType / task_type 参数。详见 官方任务指令说明。

Response Body

成功时返回 JSON 对象：

字段	类型	说明
embedding.values	number[]	本次输入生成的向量
usageMetadata.promptTokenCount	integer	输入 token 总量
usageMetadata.totalTokenCount	integer	本次请求的 token 总量，上游返回时提供
usageMetadata.promptTokensDetails	array	按模态划分的输入用量
usageMetadata.promptTokensDetails[].modality	string	模态，例如 TEXT、IMAGE、AUDIO、VIDEO
usageMetadata.promptTokensDetails[].tokenCount	integer	对应模态的 token 数量
truncated	boolean	输入是否被截断，上游返回时提供

以下为结构示意，向量仅展示前 3 个数值，usage 数值也仅用于说明；实际向量长度和用量以响应为准。

{
  "embedding": {
    "values": [0.012345, -0.023456, 0.034567]
  },
  "usageMetadata": {
    "promptTokenCount": 12,
    "totalTokenCount": 12,
    "promptTokensDetails": [
      { "modality": "TEXT", "tokenCount": 12 }
    ]
  },
  "truncated": false
}

读取向量时使用 embedding.values。本接口返回单个 embedding 对象。

调用示例

先设置 Exchange Token API Key，以下示例均使用此环境变量：

export EXCHANGE_TOKEN_API_KEY="YOUR_API_KEY"

文本向量（cURL）

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{ "text": "Exchange Token 提供统一的模型 API 接入。" }]
    }
  }'

检索查询与自定义维度（cURL）

生成 768 维查询向量。为文档建索引时，使用相同模型和维度，并将文本替换为对应的文档内容与任务格式。

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{ "text": "task: search result | query: 如何查询订单" }]
    },
    "embedContentConfig": {
      "outputDimensionality": 768
    }
  }'

文本与图片联合向量（Python）

将本地 image.png 编码为 Base64，与文本一起生成一条向量。示例仅使用 Python 标准库。

import base64
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

image_data = base64.b64encode(Path("image.png").read_bytes()).decode("ascii")
payload = {
    "content": {
        "parts": [
            {"text": "一只在草地上奔跑的小狗"},
            {"inlineData": {"mimeType": "image/png", "data": image_data}},
        ]
    },
    "embedContentConfig": {"outputDimensionality": 768},
}

request = Request(
    "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "x-goog-api-key": os.environ["EXCHANGE_TOKEN_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=120) as response:
    result = json.load(response)

values = result["embedding"]["values"]
print("Dimensions:", len(values))
print("First 5 values:", values[:5])
print("Usage:", result.get("usageMetadata"))

PDF、音频和视频也可按此方式通过 inlineData 传入。替换读取的文件、mimeType 和可选文本；仅生成文件向量时，删除文本 Part。常见类型如下，文件需满足模型限制。

输入	MIME 类型示例
图片	image/png、image/jpeg
PDF	application/pdf
音频	audio/mp3、audio/wav
视频	video/mp4、video/mpeg

引用 PDF 文件（cURL）

已有上游可读取的 Google Cloud Storage 文件时，可使用 fileData。请将 gs://YOUR_BUCKET/document.pdf 替换为实际地址，并确保上游具备读取权限；仅填写 URI 不会上传本地文件。下例开启文档 OCR。

curl --fail-with-body -sS -X POST \
  "https://api.exchangetoken.ai/v1/models/gemini-embedding-2:embedContent" \
  -H "x-goog-api-key: $EXCHANGE_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{
        "fileData": {
          "mimeType": "application/pdf",
          "fileUri": "gs://YOUR_BUCKET/document.pdf"
        }
      }]
    },
    "embedContentConfig": {
      "outputDimensionality": 768,
      "documentOcr": true
    }
  }'