Embedding 接口

接口说明

向量化模型可将文本、图像、视频等内容转换为数值向量，用于语义搜索、推荐、聚类、分类、异常检测等任务。Ling.AI 对外统一暴露 POST /v1/embeddings，并把请求纳入同一套鉴权、限流、计费和 usage_logs 链路；具体如何转发，取决于模型记录配置的真实 base_url：

请求方式 POST

请求地址 /v1/embeddings

认证方式 Authorization / x-api-key / x-goog-api-key

返回解析

同一个 /v1/embeddings 入口可能返回 OpenAI 兼容结构，也可能返回 DashScope 原生结构。生产接入时请按模型目录中的模型类型、Provider 和示例确认客户端解析逻辑。

协议路由

路由模式	适用模型	真实上游地址	说明
OpenAI兼容接口	`text-embedding-v4` 等文本模型	`https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings`	保持 OpenAI 风格请求与返回，支持 `dimensions`
DashScope 文本向量	`text-embedding-v4`、`text-embedding-v3`、`text-embedding-v2`、`text-embedding-v1`	`https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding`	支持 `dimension`、`text_type`、`instruct`、`output_type`
DashScope 多模态向量	`tongyi-embedding-vision-plus`、`tongyi-embedding-vision-flash`、`multimodal-embedding-v1`、`qwen3-vl-embedding`、`qwen2.5-vl-embedding`	`https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding`	支持多模态独立向量与多模态融合向量，使用 `contents` 结构

返回格式

如果模型记录走 OpenAI 兼容地址，响应通常是 OpenAI 风格的 data 数组；如果走 DashScope 原生地址，响应通常为 output.embeddings 结构。接入前请根据模型能力确认客户端解析方式。

OpenAI兼容接口

当 embedding 模型记录指向百炼兼容模式地址时，可直接按 OpenAI SDK 风格发起请求。此模式最适合纯文本向量场景。

参数名	类型	必填	说明
`model`	string	是	例如 `text-embedding-v4`
`input`	string \| array<string>	是	要向量化的文本内容
`dimensions`	integer	否	自定义向量维度，仅兼容模式使用该字段名
`encoding_format`	string	否	`float` 或 `base64`

curl

curl https://api.vip.lingapi.ai/v1/embeddings \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v4",
    "input": "衣服的质量杠杠的",
    "dimensions": 256
  }'

DashScope 文本向量

如果模型记录的真实地址配置为百炼文本向量原生接口，网关会自动把 input 转换为 texts 数组，并把高级参数转入 parameters。适用于需要任务指令、查询/文档角色区分、稠密与稀疏向量等高级能力的场景。

参数名	类型	必填	说明
`input`	string \| array<string>	是	网关会自动转成百炼原生的 `texts` 列表
`dimension`	integer	否	自定义向量维度。也兼容 `dimensions` 别名
`text_type`	string	否	`query` 或 `document`，用于区分查询与文档文本
`instruct`	string	否	英文任务指令，仅在特定检索场景下建议开启
`output_type`	string	否	`dense`、`sparse`、`dense&sparse`

高级能力

text-embedding-v4 支持 Batch 大规模离线处理，也支持通过 text_type 和 instruct 优化检索场景。短查询建议使用 query，底库文档建议使用 document。

curl

curl https://api.vip.lingapi.ai/v1/embeddings \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v4",
    "input": ["喜欢，以后还来这里买"],
    "dimension": 256,
    "text_type": "query",
    "instruct": "Given a product search query, retrieve relevant products",
    "output_type": "dense&sparse"
  }'

多模态独立向量

多模态独立向量适用于需要分别处理文本、图片、视频的场景。常见模型包括 tongyi-embedding-vision-plus、tongyi-embedding-vision-flash 和 multimodal-embedding-v1。通过 DashScope 原生多模态接口调用时，输入结构为 contents 数组，每个元素可以是单独的文本、图片或视频对象。

curl

curl https://api.vip.lingapi.ai/v1/embeddings \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tongyi-embedding-vision-plus",
    "input": [
      {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"},
      {"text": "衣服的质量杠杠的"}
    ],
    "dimension": 512,
    "fps": 0.5,
    "output_type": "dense"
  }'

多模态融合向量

多模态融合向量适用于文搜图、图搜图、文搜视频、跨模态检索等场景。qwen3-vl-embedding 同时支持融合向量和独立向量；qwen2.5-vl-embedding 仅支持融合向量。融合模式下，需要把文本、图像、视频放在同一个内容对象中。对于更复杂的图像输入，也可在内容对象中使用 multi_images。

字段	类型	说明
`contents`	array	多模态输入数组，每个元素是一个融合或独立内容对象
`text`	string	文本内容
`image`	string	图片 URL 或 Base64 数据
`video`	string	视频 URL
`multi_images`	array<string>	多图输入扩展字段，适用于更复杂的多图融合场景
`fps`	number	视频抽帧参数，按模型支持情况生效

curl

curl https://api.vip.lingapi.ai/v1/embeddings \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-embedding",
    "input": [
      {
        "text": "这是一段测试文本，用于生成多模态融合向量",
        "image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png",
        "video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"
      }
    ],
    "dimension": 1024
  }'

模型选择

类别	推荐模型	说明
文本向量	`text-embedding-v4`、`text-embedding-v3`、`text-embedding-v2`、`text-embedding-v1`	`text-embedding-v4` 是当前文本向量主推荐模型，支持 64-2048 多种维度与 100+ 主流语种
多模态独立向量	`tongyi-embedding-vision-plus`、`tongyi-embedding-vision-flash`、`multimodal-embedding-v1`	适合分别处理图文视频内容，常用于视频分类、图像分类、独立索引
多模态融合向量	`qwen3-vl-embedding`、`qwen2.5-vl-embedding`	适合跨模态检索。`qwen3-vl-embedding` 支持中、英、日、韩、法、德等 33种主流语言

地域与规格

向量模型在北京与 新加坡 的上架情况和价格不同。常见文本向量模型如 text-embedding-v4 同时支持北京和新加坡；多模态模型中，tongyi-embedding-vision-plus 与 tongyi-embedding-vision-flash 也支持新加坡。

模型与地域

模型、Endpoint URL 与 API Key 必须属于同一地域。对于北京地域，通常使用 dashscope.aliyuncs.com；对于新加坡地域，通常使用 dashscope-intl.aliyuncs.com。

📚 相关阅读

API 认证指南 | 模型目录

Embeddings API

接口说明

返回解析

协议路由

返回格式

OpenAI兼容接口

DashScope 文本向量

高级能力

多模态独立向量

多模态融合向量

模型选择

地域与规格

模型与地域

📚 相关阅读