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

# Create embeddings

从文本或媒体输入创建 embedding 向量。纯文本请求每条输入返回一个向量，适用于检索、语义搜索、聚类、分类和 RAG。包含媒体（以 base64 data URI 形式传入的图片、音频或视频）的请求会将**所有**输入融合为**单个**跨模态向量——如需每个资产各得一个向量，请将每个资产放在单独的请求中进行 embedding。兼容 OpenAI Embeddings API 格式。此端点不支持流式传输。

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer 令牌。在 Authorization 请求头中使用您的 API 密钥作为 Bearer 令牌。

  格式：`Bearer <SUNRA_KEY>`
</ParamField>

## 请求

此端点接受一个 JSON 对象。

<ParamField body="model" type="string" required>
  要使用的 embedding 模型 ID，例如 `google/gemini-embedding-2`。可用的 embedding 模型见[模型页面](https://sunra.ai/models)。
</ParamField>

<ParamField body="input" type="string | string[]" required>
  要进行 embedding 的输入，可以是单个字符串或字符串数组。纯文本输入独立进行 embedding，按输入顺序每条返回一个向量。媒体输入以 base64 data URI 形式传入（`data:image/png;base64,…`、`data:audio/mpeg;base64,…`、`data:video/mp4;base64,…`），可与文本混合——但任何包含媒体的请求都会为全部输入返回一个融合后的单一向量。限制（来自上游）：每个请求最多 6 张图片，视频最长 120 秒，所有模态合计不超过 8,192 个 token（按文本 token 计；图片每张 258 个 token，音频每秒 25 个 token，视频每秒 66 个 token）。
</ParamField>

<ParamField body="dimensions" type="integer">
  输出 embedding 的维度数。仅支持具有灵活输出维度（Matryoshka Representation Learning）的模型。`google/gemini-embedding-2` 默认为 `3072`，支持 `128` 到 `3072` 之间的值。较小的值会截断向量，同时保留大部分语义质量。
</ParamField>

<ParamField body="encoding_format" type="string">
  返回 embedding 的格式。`float`（默认）或 `base64`。
</ParamField>

## 响应

<ResponseField name="object" type="string">
  始终为 `list`。
</ResponseField>

<ResponseField name="data" type="object[]">
  embedding 对象列表，每条输入对应一个，按输入顺序排列。

  <Expandable title="embedding 对象">
    <ResponseField name="object" type="string">
      始终为 `embedding`。
    </ResponseField>

    <ResponseField name="index" type="integer">
      对应输入的索引。
    </ResponseField>

    <ResponseField name="embedding" type="number[]">
      embedding 向量。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  用于创建 embedding 的模型。
</ResponseField>

<ResponseField name="usage" type="object">
  本次请求的 token 用量。embedding 仅按输入 token 计费，各模态费率不同（定价见模型页面）。包含媒体的请求会返回按模态细分的 token 数。

  <Expandable title="usage 对象">
    <ResponseField name="prompt_tokens" type="integer">
      文本输入的 token 数。
    </ResponseField>

    <ResponseField name="input_image_tokens" type="integer">
      图片输入的 token 数（每张 258 个）。仅当请求包含图片时返回。
    </ResponseField>

    <ResponseField name="input_audio_tokens" type="integer">
      音频输入的 token 数（每秒 25 个）。仅当请求包含音频时返回。
    </ResponseField>

    <ResponseField name="input_video_tokens" type="integer">
      视频输入的 token 数（每秒 66 个）。仅当请求包含视频时返回。
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      所有模态的输入 token 总数（embedding 不产生输出 token）。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/embeddings \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-embedding-2",
      "input": [
        "The quick brown fox jumps over the lazy dog.",
        "Sunra is a platform for AI models."
      ],
      "dimensions": 768
    }'
  ```

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

  response = requests.post(
      "https://api-llm.sunra.ai/v1/embeddings",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "google/gemini-embedding-2",
          "input": [
              "The quick brown fox jumps over the lazy dog.",
              "Sunra is a platform for AI models."
          ],
          "dimensions": 768
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/embeddings", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "google/gemini-embedding-2",
      input: [
        "The quick brown fox jumps over the lazy dog.",
        "Sunra is a platform for AI models."
      ],
      dimensions: 768
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.011253, -0.020551, 0.049236, "..."]
      },
      {
        "object": "embedding",
        "index": 1,
        "embedding": [0.031744, 0.008122, -0.014307, "..."]
      }
    ],
    "model": "google/gemini-embedding-2",
    "usage": {
      "prompt_tokens": 18,
      "total_tokens": 18
    }
  }
  ```
</ResponseExample>