创建向量

把一段或多段文本转换成向量，适合检索增强（RAG）、语义搜索和去重；需要按与查询的相关度给文档排序时，用文档重排。接口采用 OpenAI Embeddings API 的格式，OpenAI SDK 的 client.embeddings.create() 把 Base URL 设为 https://api.lyrouter.com/v1 即可使用；请求和响应都是 JSON，不支持流式。网关只把 model 换成服务商的真实模型名，其余字段原样转发，所以参数和响应格式以模型所属服务商为准。

POST/v1/embeddings

鉴权

在请求头中携带 API Key：

Authorization: Bearer <API Key>

Bearer 区分大小写。也可以改用 x-api-key: <API Key>，两者同时存在时只读 Authorization。API Key 在工作空间的 API 密钥 页面创建，只用于 LYRouter 鉴权，不会转发给上游服务商。完整说明见接入地址与鉴权，环境变量 LYROUTER_API_KEY 的设置见完成第一次模型调用。

请求头

请求头	必填	说明
`Content-Type`	是	`application/json`，其他类型返回 400

请求体

参数	类型	必填	说明
`model`	string	是	向量模型 ID，获取方法见下文「选择模型」。请始终写明：不写时使用工作空间的默认模型，而默认模型通常是对话模型，落到它上面会返回 400 `unsupported_model_api` 或上游的错误，见下文「网关行为」
`input`	string \| array	是	一段文本，或文本数组（一次生成多条向量）。单次条数、单条长度上限由服务商决定
`encoding_format`	string	否	`float`（数字数组）或 `base64`。透传给上游，是否支持取决于模型
`dimensions`	integer	否	输出向量的维度。透传给上游，是否生效取决于模型
`user`	string	否	终端用户标识。透传给上游，是否生效取决于模型

表中没有列出的字段原样转发给上游，是否生效取决于模型。

选择模型

可用的向量模型以工作空间的模型广场为准：在模型广场搜索 embedding 等关键词，复制模型 ID 替换示例中的 MODEL_ID。

也可以用 GET /v1/models 筛选。返回的每个模型带 api_types 字段，含 embeddings 的可调用本接口：

curl -s https://api.lyrouter.com/v1/models \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  | jq -r '.data[] | select((.api_types // []) | index("embeddings")) | .id'

模型没有声明 api_types 时不会出现在筛选结果里，可以在模型广场确认。字段说明见列出模型，筛选重排模型的方法见文档重排。

请求示例

curl https://api.lyrouter.com/v1/embeddings \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "input": ["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
    "encoding_format": "float"
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
result = client.embeddings.create(
    model="MODEL_ID",
    input=["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
    encoding_format="float",
)
for item in result.data:
    print(item.index, len(item.embedding))
print(result.usage)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const result = await client.embeddings.create({
  model: "MODEL_ID",
  input: ["LYRouter 是可信模型服务与 Token 治理平台", "用一个 API Key 调用多家模型"],
  encoding_format: "float",
});
for (const item of result.data) {
  console.log(item.index, item.embedding.length);
}
console.log(result.usage);

OpenAI 官方 SDK 在没有指定 encoding_format 时会请求 base64 并在本地解码。如果上游不支持 base64 而报错，像上例一样显式传 encoding_format="float"。

响应

成功时返回一个 list 对象，data 中每条输入对应一个向量；出错时返回 error 对象。下面的 200 是 OpenAI 兼容服务商的典型响应（向量已截短），400 是请求落到了不支持向量接口的模型（多为默认模型，见下文「网关行为」），403 是模型没有在本工作空间开通且工作空间没有设置默认模型。

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [-0.0211, 0.0334, 0.0102] }
  ],
  "model": "MODEL_ID",
  "usage": { "prompt_tokens": 19, "total_tokens": 19 }
}

{
  "error": {
    "message": "This model does not support the embeddings API",
    "type": "invalid_request_error",
    "code": "unsupported_model_api"
  }
}

{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}

字段	说明
`data[].index`	对应 `input` 数组中的位置，按它对齐，不要依赖返回顺序
`data[].embedding`	向量。`encoding_format` 为 `base64` 时是 Base64 字符串
`model`	上游返回的模型名，可能与请求中的模型 ID 写法不同；实际使用的模型以日志的「模型（实际）」为准
`usage.prompt_tokens`	本次输入的 Token 数，即计费数量。在日志中记为「输入（缓存未命中）」，「输出」「输入（缓存命中）」「显式缓存创建」均为 0
`usage.total_tokens`	与 `prompt_tokens` 相同

计费

按输入 Token 数计费，取自响应的 usage.prompt_tokens。单价以模型广场为准，每次调用的实际费用在日志中查看。费用估算方法见调用费用与缓存计费。

网关行为

请求原样转发：网关只把 model 换成通道的真实模型名，其余字段原样转发（通过虚拟模型调用时见下文）。网关会重新编码 JSON：对象的键按固定顺序排列，数字最多保留 14 位有效数字。
通道回退：同一模型有多个通道时，按工作空间的路由策略依次尝试，前一个通道失败就换下一个。
默认模型兜底：工作空间在智能路由中设置了默认模型时，下面三种情况会落到默认模型上。默认模型通常是对话模型，此时得到的是报错，而不是你预期的结果（默认模型声明了 api_types 时，网关返回 400 This model does not support the embeddings API；没有声明时，请求会转发给上游，由上游报错，见下文「常见错误」）：
- 请求没写 model；
- model 写错，或该模型没有在本工作空间开通；
- 该模型的所有通道都失败了。这时上游的真实报错被默认模型的报错取代，请到日志详情的「上游调用尝试」查看前面每次尝试的原因。
虚拟模型与 Auto：虚拟模型可以用于本接口，前提是它的模型列表全部是向量模型；虚拟模型的系统提示词不会注入，但设置的推理参数会按字段名合并进请求体，因此给向量接口使用的虚拟模型不要设置推理参数。lyrouter/auto 的候选是对话模型，不要用于本接口。目前网关不会拒绝这类请求：请求会挂起约 2 分钟，之后返回 HTTP 200，响应体是上游的原生错误（如 {"vectors":null,"base_resp":{"status_code":2013,...}}）而不是向量列表，只看状态码的程序会误以为成功；使用 HTTP/2 时连接还可能中途断开。
安全围栏：安全围栏的封禁、模型访问控制和客户端访问控制照常生效；敏感信息、提示词注入和意图安全检测不作用于本接口。

常见错误

错误响应为 {"error":{"message":"...","type":"...","code":"..."}}，code 只有部分错误才有。

状态码	`error.message`	`error.code`	原因与处理
400	`This model does not support the embeddings API`	`unsupported_model_api`	所用模型声明了 `api_types` 且不支持向量接口，多为请求落到了默认模型，见上文「默认模型兜底」。写上正确的向量模型 ID
400	`you must provide a model parameter`	`missing_model`	没写 `model`，工作空间也没有默认模型
400	`unsupported content-type: <类型>, only application/json is supported`	—	`Content-Type` 不是 JSON。响应体是一行纯文本，但响应头 `Content-Type` 目前是 `application/json`，解析前先判断正文是否为 JSON
403	`Model is not available in the model plaza`	`model_not_available`	模型没有在本工作空间开通，且没有设置默认模型。请管理员在模型广场开通，或换用已开通的模型
503	`all routed candidates exhausted`	`no_route_candidate`	找不到可服务这次请求的通道，见模型不可用

输入超长、条数超限等由上游服务商返回，状态码和报错原文由上游决定。
用没有声明 api_types 的对话模型（见列出模型）调用本接口时，不会收到 400 unsupported_model_api：请求会转发给上游，由上游报错，可能要等待较长时间。例如某对话模型约 60 秒后返回上游的 404 Unsupported model `<模型>` for OpenAI compatibility mode.，error.code 为 model_not_supported。
网关先解析模型，再检查 Content-Type：没写 model 或模型没有开通时，先返回模型相关的错误（400 missing_model、403 model_not_available）；模型有效时才返回 400 unsupported content-type: …。
401 / 403 鉴权问题见401 / 403：鉴权与权限，429 见429：限流与配额。完整列表见错误码与请求标识。