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

# Gemini 文本向量（embedContent）

> 使用 Gemini 原生接口将文本转换为向量嵌入

## 简介

使用 Gemini 原生接口将文本转换为向量嵌入。模型由 URL 路径 指定（如 `gemini-embedding-001`），适用于需要 Google 嵌入模型或与 Gemini API 对齐的场景。

与 [文本向量化（Embedding）](/docs/zh-Hans/api-reference/endpoint/embeddings) 的 OpenAI 格式互为补充：本文档为 Gemini 原生路径；同一能力也可通过 `POST /v1/embeddings` 调用。

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 路径参数

**model** `string` *required*

嵌入模型名称，如 `gemini-embedding-001`。

## 请求参数

**content** `object` *required*

待嵌入内容。须包含 `parts` 数组，每项为 `{ "text": "文本内容" }`。

**outputDimensionality** `integer`

输出向量维度（仅部分模型支持，如 `gemini-embedding-001`、`text-embedding-004`）。

**taskType** `string`

任务类型，如 `RETRIEVAL_DOCUMENT`、`RETRIEVAL_QUERY`（可选）。

## 代码示例

**cURL**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "content": {
      "parts": [
        { "text": "要嵌入的文本内容" }
      ]
    }
  }'
```

**cURL（带维度）**

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "content": {
      "parts": [
        { "text": "要嵌入的文本内容" }
      ]
    },
    "outputDimensionality": 768
  }'
```

**Python**

```python theme={null}
import requests

url = "https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxxxx"
}
payload = {
    "content": {
        "parts": [
            { "text": "要嵌入的文本内容" }
        ]
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
embedding = data["embedding"]["values"]
print(f"向量维度：{len(embedding)}")
```

## 响应示例

```json theme={null}
{
  "embedding": {
    "values": [0.0023064255, -0.009327292, 0.015797347, ...]
  },
  "metadata": {
    "usage": {
      "prompt_tokens": 6,
      "total_tokens": 6
    }
  }
}
```

## 批量接口（batchEmbedContents）

批量嵌入请使用：`POST /v1/models/{model}:batchEmbedContents`，请求体为 `requests` 数组，每项结构同单条（含 `content.parts`），且 **不要** 在每项中带 `model` 字段。

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/models/gemini-embedding-001:batchEmbedContents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "requests": [
      { "content": { "parts": [{ "text": "第一段文本" }] } },
      { "content": { "parts": [{ "text": "第二段文本" }] } }
    ]
  }'
```

## 支持的模型

| 模型 | 说明 |
| - | - |
| gemini-embedding-001 | 通用嵌入模型，支持 `outputDimensionality` |
| text-embedding-004 | 高精度嵌入模型 |

## 注意事项

* `content.parts` 必填，至少一个 `text` 非空
* 模型由 URL 路径指定，请求体不要包含 `model` 字段
* 用量信息在响应的 `metadata.usage` 中（`prompt_tokens`、`total_tokens`）

> [!TIP]
>
> 如果您的应用已使用 OpenAI SDK，建议使用 `/v1/embeddings` 兼容接口以减少代码改动。

```bash cURL theme={null}
curl --request POST \
  --url https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "content": {
      "parts": [{"text": "这是一段测试文本"}]
    }
  }'
```

```python Python theme={null}
import requests

url = "https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent"
headers = {
    "Authorization": "Bearer sk-xxxxxxxxxx",
    "Content-Type": "application/json"
}
payload = {
    "content": {
        "parts": [{"text": "这是一段测试文本"}]
    }
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-xxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: {
      parts: [{ text: '这是一段测试文本' }]
    }
  })
});
const data = await response.json();
console.log(data);
```

```php PHP theme={null}
<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent', [
    'headers' => [
        'Authorization' => 'Bearer sk-xxxxxxxxxx',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'content' => [
            'parts' => [['text' => '这是一段测试文本']]
        ]
    ]
]);
echo $response->getBody();
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "content": map[string]interface{}{
            "parts": []map[string]string{
                {"text": "这是一段测试文本"},
            },
        },
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}
```

```java Java theme={null}
import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
        "content": {"parts": [{"text": "这是一段测试文本"}]}
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent"))
    .header("Authorization", "Bearer sk-xxxxxxxxxx")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

```ruby Ruby theme={null}
require 'net/http'
require 'json'

uri = URI('https://api.mixroute.ai/v1/models/gemini-embedding-001:embedContent')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
request['Content-Type'] = 'application/json'
request.body = {
  content: { parts: [{ text: '这是一段测试文本' }] }
}.to_json

response = http.request(request)
puts response.body
```

```json Response theme={null}
{
  "embedding": {
    "values": [0.0023064255, -0.009327292, 0.015797347]
  },
  "metadata": {
    "usage": {
      "prompt_tokens": 6,
      "total_tokens": 6
    }
  }
}
```


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