Gemini Embeddings接口（向量嵌入）

# Gemini-Embedding-2-Preview 向量化 API 对接文档

> **用途**：第三方软件 / 自有应用对接「Gemini Embedding 2 全模态向量化」能力
> **平台**：云灵API（api.cxsee.com）
> **适用对象**：平台注册会员（需有可用令牌与余额）
> **协议**：**双接口支持** —— OpenAI 兼容 `/v1/embeddings` **与** Gemini 原生 `/v1beta/models/{model}:embedContent`
> **模型**：`gemini-embedding-2-preview`（首个原生全模态嵌入模型：文本 / 图片 / 视频 / 音频 / PDF）

---

## ⚠️ 四个必须先知道的点

1. **必须用模型名 `gemini-embedding-2-preview`**。用 `gemini-embedding-001` 会报 **503 无可用渠道**（平台未给该名下配置渠道）。
2. **降维（Matryoshka）只能用官方接口**。`/v1/embeddings` 传 `dimensions` 会被**静默忽略**（永远返回 3072 维）；要截断维度必须用官方接口的 **`outputDimensionality`**。
3. **默认输出 3072 维**，可截断至 1536 / 768 / 256（实测均生效）。
4. **没有 `taskType` 效果**：传 `taskType`（RETRIEVAL_QUERY 等）**实测不改变向量**（直连上游同样如此，非平台问题）。

---

## 1. 快速开始

### 1.1 方式 A：OpenAI 兼容接口（推荐，最简单）

```bash
curl -X POST "https://api.cxsee.com/v1/embeddings" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-embedding-2-preview",
    "input": "你好，这是向量化测试文本。"
  }'
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.033039607, -0.009822987, 0.013949812, ...]
    }
  ],
  "model": "gemini-embedding-2-preview",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}
```

> 向量为 **3072 维浮点数组**（上面已截断显示）。

### 1.2 方式 B：Gemini 官方接口（支持降维）

```bash
curl -X POST "https://api.cxsee.com/v1beta/models/gemini-embedding-2-preview:embedContent" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-embedding-2-preview",
    "content": { "parts": [ { "text": "你好，这是向量化测试文本。" } ] },
    "outputDimensionality": 768
  }'
```

```json
{
  "embedding": {
    "values": [-0.033039607, -0.009822987, 0.013949812, ...]
  }
}
```

> `outputDimensionality: 768` → 返回 **768 维**向量。

---

## 2. 鉴权方式

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 令牌获取 | 登录控制台 →「令牌」页面创建；或注册 / OAuth / 微信登录后自动生成的默认密钥 |
| 内容类型 | `Content-Type: application/json` |

> 令牌以 `sk-` 开头。未认证或令牌失效返回 `401`。

**Base URL：`https://api.cxsee.com`**

---

## 3. 接口总览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/v1/embeddings` | **OpenAI 兼容**接口（单条 / 批量；**不支持降维**） |
| POST | `/v1beta/models/{model}:embedContent` | **Gemini 官方**接口（单条；**支持 `outputDimensionality` 降维**） |
| POST | `/v1beta/models/{model}:batchEmbedContents` | **Gemini 官方**接口（批量） |

**可用模型名**：`gemini-embedding-2-preview`

---

## 4. 方式 A：OpenAI 兼容接口 `/v1/embeddings`

### 4.1 请求参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 固定 `gemini-embedding-2-preview` |
| `input` | string \| string[] | 是 | 单条文本，或**文本数组（批量）** |
| `dimensions` | int | 否 | ⚠️ **实测被静默忽略**，永远返回 3072 维。降维请用官方接口 |
| `encoding_format` | string | 否 | `float`（默认）/ `base64`，实测均返回浮点数组 |

### 4.2 批量示例

返回 `data` 数组含 3 条向量（每条 3072 维）。

---

## 5. 方式 B：Gemini 官方接口

### 5.1 `embedContent`（单条）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | `models/gemini-embedding-2-preview`（**建议带 `models/` 前缀**） |
| `content.parts[].text` | string | 二选一 | 文本输入 |
| `content.parts[].inlineData` | object | 二选一 | **图片 / 多模态输入**（`mimeType` + `data` base64） |
| `outputDimensionality` | int | 否 | **降维**：3072（默认）/ 1536 / 768 / 256，实测均生效 |
| `taskType` | string | 否 | ⚠️ 实测**不改变结果**（上游不支持） |

### 5.2 `batchEmbedContents`（批量）

```bash
curl -X POST "https://api.cxsee.com/v1beta/models/gemini-embedding-2-preview:batchEmbedContents" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "model": "models/gemini-embedding-2-preview", "content": { "parts": [ { "text": "文本一" } ] } },
      { "model": "models/gemini-embedding-2-preview", "content": { "parts": [ { "text": "文本二" } ] } }
    ]
  }'
```

---

## 6. 多模态输入

本模型的**核心卖点**是**全模态统一向量空间**：文本、图片、视频、音频、PDF 都映射到同一空间。

### 6.1 图片输入（官方接口）

```bash
curl -X POST "https://api.cxsee.com/v1beta/models/gemini-embedding-2-preview:embedContent" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-embedding-2-preview",
    "content": {
      "parts": [
        { "inlineData": { "mimeType": "image/png", "data": "<图片 base64>" } }
      ]
    }
  }'
```

### 6.2 图文交错输入

```json
"content": {
  "parts": [
    { "text": "这是一张图片：" },
    { "inlineData": { "mimeType": "image/png", "data": "<图片 base64>" } }
  ]
}
```

> 实测纯图片、图文交错均返回 200，且 `cos(纯图片, 图文交错) = 0.80`（同一图不同输入方式高度一致）。
> 图片 token 会折算计入 `usageMetadata`，费用相应上升。

---

## 7. 返回字段说明

### 兼容接口 `/v1/embeddings`

| 字段 | 说明 |
|---|---|
| `data[].embedding` | 浮点数组，默认 **3072 维** |
| `data[].index` | 对应输入顺序 |
| `model` | 模型名 |
| `usage.prompt_tokens` | 输入 token 数 |

### 官方接口 `:embedContent`

| 字段 | 说明 |
|---|---|
| `embedding.values` | 浮点数组，维度由 `outputDimensionality` 决定 |

> **两接口返回的向量完全相同**（同文本 cos 相似度 = **1.000000**），确认走同一底层模型。

---

## 8. 语义有效性（实测验证）

| 对比 | cos 相似度 | 说明 |
|---|---|---|
| 「今天天气真好」 vs 「外面阳光灿烂」 | **0.8689** | 语义相近 ✅ |
| 「我是一个程序员」 vs 「我从事软件开发工作」 | **0.7612** | 语义相近 ✅ |
| 「今天天气真好」 vs 「股票市场今日大幅下跌」 | **0.5394** | 语义无关 ✅ |
| 「今天天气真好」 vs 「我是一个程序员」 | **0.4876** | 语义无关 ✅ |

> 相似文本显著高于无关文本，**向量化真实有效**，可用于语义检索 / 聚类 / 去重。

---

## 9. 错误码

| HTTP | 场景 | 返回示例 |
|---|---|---|
| `400` | `input` 为空 | `...parts[0].data: required oneof field 'data' must have one initialized field` |
| `401` | 未带 / 令牌无效 | `无效的令牌` |
| `503` | 模型名不存在（如 `gemini-embedding-001`） | `分组 gemini优质 下模型 gemini-embedding-001 无可用渠道` |

> 失败请求不扣费。

---

## 10. 计费说明

| 项 | 单价 |
|---|---|
| 输入（文本） | **约 $3.00 / 1M tokens** |

- 计费依据 `usage.prompt_tokens`；`$1 = 500000 算力值（quota）`。
- **实测样例**：输入 14 tokens → 实扣 **$0.000042**；输入 9301 tokens → 实扣 **$0.0279**。
- 多模态输入（图片）会折算为更多 token，费用相应上升。

---

## 11. 常见问题

**Q1：怎么把向量从 3072 维降到 768 维？**
A：`/v1/embeddings` 的 `dimensions` **无效**，必须用官方接口：
`/v1beta/models/gemini-embedding-2-preview:embedContent` + `"outputDimensionality": 768`。

**Q2：两个接口的向量一样吗？**
A：一样（实测 cos = 1.000000）。日常用兼容接口更简单；要降维 / 多模态，用官方接口。

**Q3：为什么传 `taskType` 没变化？**
A：实测该参数**不改变向量**（RETRIEVAL_QUERY / RETRIEVAL_DOCUMENT / CLASSIFICATION 等 6 种取值结果 md5 完全相同），**直连上游也如此** → 上游未实现该能力。文档不建议依赖它。

**Q4：支持哪些模态？**
A：文本、图片、视频、音频、PDF（官方宣传的全模态）。本平台实测**文本、图片、图文交错**均可用；音视频/PDF 建议咨询平台确认传入方式。

**Q5：最大输入长度？**
A：实测 **9301 tokens 成功**。官方宣称支持长上下文，具体上限建议按场景自测。

---

## 12. 完整可运行示例（Python）

```python
import requests, numpy as np

KEY = "<你的API令牌>"
BASE = "https://api.cxsee.com"

# 方式 A：OpenAI 兼容（3072 维）
r = requests.post(f"{BASE}/v1/embeddings",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"model": "gemini-embedding-2-preview", "input": ["文本一", "文本二"]},
    timeout=60).json()
vA = [d["embedding"] for d in r["data"]]
print("兼容接口:", len(vA), "条, 维度", len(vA[0]))

# 方式 B：官方接口 + 降维 768
r2 = requests.post(f"{BASE}/v1beta/models/gemini-embedding-2-preview:embedContent",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "models/gemini-embedding-2-preview",
        "content": {"parts": [{"text": "文本一"}]},
        "outputDimensionality": 768,
    }, timeout=60).json()
vB = r2["embedding"]["values"]
print("官方接口:", "维度", len(vB))  # 768

# 余弦相似度
def cos(a, b):
    a, b = np.array(a), np.array(b)
    return float(a @ b / (np.linalg.norm(a) * np.linalg.norm(b)))

print("相似度:", cos(vA[0], vA[1]))
```

---

*文档基于 2026-10-12 平台实测校准。*

上一篇：Gemini-TTS 语音合成 API文档下一篇：Gemini-Nano-Banana-2.1 图像生成 API