POST/v1/embeddings

创建文本嵌入向量

将单条或多条文本转换为向量，供语义检索与相似度计算使用。

API Key application/json

功能与适用场景

Embedding 返回数值向量，不生成自然语言回答。一个输入元素对应一个向量，用于建立索引或检索。

支持模型与组合

text-embedding-3-small 默认1536维，text-embedding-3-large 默认3072维；示例将 small 缩减到768维。两种模型的向量不能混在同一索引直接比较。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。

第二步：调用模型

POST https://top.qingyuntop.ai/v1/embeddings

请求为 application/json。

Request

请求

/v1/embeddings

Body

必填

Bodyobject

modelstring必填

必填，顶层。OpenAI 示例 text-embedding-3-small；Gemini 兼容示例 gemini-embedding-001。

inputstring / array必填

必填，非空字符串或字符串数组。每个数组元素对应一个向量，不把多个文档拼成一个字符串。；分支：string / array<string>

dimensionsinteger

选填，正整数。OpenAI text-embedding-3-small 默认1536，large 默认3072，可缩减；Gemini 兼容示例768，仅对文中列出的型号设置。

encoding_formatstring

选填，默认 float；本页明确用 float 返回数字数组，base64 需要另外解码。；可选：float / base64；默认：float

示例float

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例application/json

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "model": "text-embedding-3-small",
  "input": [
    "如何重置密码？",
    "忘记密码怎么办？"
  ],
  "encoding_format": "float",
  "dimensions": 768
}''')
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

objectstring必填

dataarray必填

数组，按 index 关联输入。embedding 为所选格式的向量；空结果要作为失败处理。

元素object

数组元素。

objectstring

embeddingarray<number>

元素number

数组元素。

indexinteger

modelstring必填

usageobject必填

prompt_tokensinteger必填

total_tokensinteger必填

响应示例json

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... (1536 floats total for ada-002)
        -0.0028842222
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

常见错误与参考

单条输入不能为空；每条输入和整批 token 均有限制，批量应按 token 拆分。text-embedding-3 通常每条最大8192 token，整批总量不超过300000 token。

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。

OpenAI 公共 API 规范。嵌入响应与索引约定。