> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/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）](/cn/api-reference/endpoint/embeddings) 的 OpenAI 格式互为补充：本文档为 Gemini 原生路径；同一能力也可通过 `POST /v1/embeddings` 调用。

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 路径参数

<ParamField path="model" type="string" required>
  嵌入模型名称，如 `gemini-embedding-001`。
</ParamField>

## 请求参数

<ParamField body="content" type="object" required>
  待嵌入内容。须包含 `parts` 数组，每项为 `{ "text": "文本内容" }`。
</ParamField>

<ParamField body="outputDimensionality" type="integer">
  输出向量维度（仅部分模型支持，如 `gemini-embedding-001`、`text-embedding-004`）。
</ParamField>

<ParamField body="taskType" type="string">
  任务类型，如 `RETRIEVAL_DOCUMENT`、`RETRIEVAL_QUERY`（可选）。
</ParamField>

## 代码示例

<Tabs>
  <Tab title="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": "要嵌入的文本内容" }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="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
      }'
    ```
  </Tab>

  <Tab title="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)}")
    ```
  </Tab>
</Tabs>

## 响应示例

```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` 兼容接口以减少代码改动。
</Tip>

<RequestExample>
  ```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
  ```
</RequestExample>

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