> ## 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）](/zh-hant/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>