POST/v1/embeddings

Gemini：OpenAI Embeddings 兼容格式

通过 /v1/embeddings 批量提交文本并获取带 index 的向量。

API Key application/json

功能与适用场景

适用于已有 OpenAI Embeddings 客户端。它是向量接口兼容，不是 Chat Completions，不返回聊天文字。

支持模型与组合

本例 gemini-embedding-001，dimensions=768。需要 Embedding 2 或 taskType 等原生字段时使用原生嵌入页。

第一步：设置鉴权

使用青云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 参数

参数	位置	类型	必填	说明	示例
`Content-Type`	Header	string	否	-	application/json
`Accept`	Header	string	否	-	application/json
`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": "gemini-embedding-001",
  "input": [
    "如何重置密码？",
    "如何修改邮箱？"
  ],
  "dimensions": 768,
  "encoding_format": "float"
}''')
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

dataarray

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

元素object

数组元素。

objectstring

indexinteger

embeddingarray<number>

元素number

数组元素。

常见错误与参考

只有本文列出的型号使用 dimensions 示例。原生可用参数不等于兼容接口都会保留；要精确控制任务类型时选择原生。

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

Google 官方 generateContent 示例。原生嵌入。