创建 Embedding¶

将文本或多模态内容转换为向量，并从 data[].embedding 读取结果。文本和多模态输入使用同一接口，但 input 的结构不同；本页以文本输入说明最小请求。

POST https://token.moi.matrixorigin.cn/v1/embeddings

调用前准备¶

请求地址为 https://token.moi.matrixorigin.cn/v1/embeddings。准备具有 Genesis 权限的访问凭据，以及支持 Embeddings 的模型 ID。

下方示例使用：

$GENESIS_ACCESS_TOKEN：实际访问令牌或服务账号 API Key，通过 Authorization Header 传递。
$MODEL_ID：要调用的模型 ID，填入请求体的 model 字段。

请求头¶

请求头	是否必填	说明
`Authorization`	是	使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。
`Content-Type`	是	设置为 `application/json`。

请求体¶

请求体包含以下字段。

本文中，类型后的 [] 表示数组，例如 string[] 是字符串数组；字段路径中的 [] 表示数组中的每一项，例如 data[].index 表示 data 数组中每一项的 index 字段。

字段	类型	是否必填	说明
`model`	string	是	支持 Embeddings 的模型 ID。
`input`	string、string[] 或 object[]	是	待转换内容。文本输入可使用字符串或字符串数组；多模态输入使用对象数组。
`encoding_format`	string	否	向量编码格式。示例使用 `float`。
`dimensions`	integer	否	期望的向量维度，仅在所选模型支持时使用。

文本批量输入时，响应的 data[].index 对应请求数组下标。多模态输入、编码格式和维度的可用性以当前模型支持范围为准。

请求示例¶

curl -X POST "https://token.moi.matrixorigin.cn/v1/embeddings" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "input": [
      "MatrixOne 是面向智能时代的数据库。",
      "Genesis 提供模型调用接口。"
    ],
    "encoding_format": "float"
  }'

成功响应¶

{
  "object": "list",
  "model": "<MODEL_ID>",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.018, -0.042, 0.337]
    }
  ]
}

响应中用于读取向量结果的字段如下。

本文中，类型后的 [] 表示数组，例如 number[] 是数值数组；字段路径中的 [] 表示数组中的每一项，例如 data[].embedding 表示 data 数组中每一项的 embedding 字段。

字段	类型	说明
`object`	string	响应对象类型，示例为 `list`。
`model`	string	实际处理请求的模型 ID。
`data`	array	本次输入产生的向量列表。
`data[].object`	string	向量对象类型，示例为 `embedding`。
`data[].index`	integer	对应文本输入数组的下标。
`data[].embedding`	number[] 或 string	向量结果。实际类型取决于请求的编码格式。

将 data[].index 映射回提交时保存的业务 ID。不要假定所有模型或编码格式都返回相同的向量维度。

错误响应¶

接口不使用 code、msg、data 包络。收到非成功 HTTP 状态时，不要从 data[] 读取向量。错误对象由兼容的模型服务返回；除 error.message 外的字段可能省略。

错误对象字段¶

{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}

错误正文中可能出现的字段如下。

字段	类型	说明
`error.message`	string	可读错误信息。
`error.type`	string，可选	上游错误类别。
`error.code`	string 或 null，可选	上游错误代码。

常见 HTTP 错误¶

下表说明收到不同 HTTP 状态时应执行的操作。

HTTP 状态码	错误代码	常见原因	建议操作
`400`	—	输入形态、向量编码或维度参数不符合当前模型要求。	先使用单个文本和 `encoding_format: "float"` 验证。
`401`	—	凭据无效，或当前凭据无权调用该模型。	检查认证 Header 和模型范围。
`403`	—	凭据无效，或当前凭据无权调用该模型。	检查认证 Header 和模型范围。
`413`	—	输入内容超过接口允许范围。	拆分批次并记录未完成项。
`429`	—	当前服务受到限制或暂时不可用。	降低请求频率，或稍后再次提交请求。
`5xx`	—	当前服务受到限制或暂时不可用。	降低请求频率，或稍后再次提交请求。

后续操作¶

最后更新于 2026 年 8 月 22 日