青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/v1beta/models/gemini-embedding-001:embedContent

Gemini Embedding 001：单条与批量文本向量

使用 embedContent / batchEmbedContents，按任务类型创建检索向量。

API Key application/json

功能与适用场景

适合文本检索、语义相似度和分类。单条 content 与批量 requests 的结构不同，均不是 generateContent。

支持模型与组合

gemini-embedding-001，默认3072维，本例768。检索文档使用 RETRIEVAL_DOCUMENT，查询使用 RETRIEVAL_QUERY；语义相似度使用 SEMANTIC_SIMILARITY。

第一步：设置鉴权

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

第二步：调用模型

POST https://top.qingyuntop.ai/v1beta/models/gemini-embedding-001:embedContent

请求为 application/json。

Request

请求

/v1beta/models/gemini-embedding-001:embedContent

Body

必填
Bodyapplication/json
Bodyobject
contentobject

embedContent 必填的单个 content 对象，parts 包含待嵌入文字；不是聊天接口的 contents 数组。

partsarray<object>
元素object
textstring
output_dimensionalityinteger

输出嵌入的可选降维。

taskTypestring

选填，无默认任务声明。文本检索文档用 RETRIEVAL_DOCUMENT，查询用 RETRIEVAL_QUERY，语义相似度用 SEMANTIC_SIMILARITY。

model（路径）string必填

必填，在 /v1beta/models/{model}:动作 中填写；generateContent 请求体无需重复 model。

modelstring

原生嵌入请求填写 models/ 加准确模型 ID，与路径一致；例如 models/gemini-embedding-001 或 models/gemini-embedding-2。批量请求中每条都携带该字段。

outputDimensionalityinteger

选填，正整数。gemini-embedding-001 与 gemini-embedding-2 默认3072维，常用768 / 1536 / 3072；同一索引保持模型、维度与归一化规则一致。字段使用 camelCase。

requestsarray

batchEmbedContents 必填，每项为完整 embedContent 请求（model、content 及可选任务和维度）。返回 embeddings 数组按输入顺序对应。

contentsarray<object>必填

必填，顶层 content 数组。role 使用 user / model，parts 保持原始顺序；下一轮重新发送历史。

元素object

数组元素。

rolestring

可选：user / model

partsarray<object>

每条 content 必填。文本 {text:...}；媒体 {inlineData:{mimeType,data}}；一张图片一个 part，顺序影响引用。

元素object

数组元素。

textstring
inlineDataobject

本地素材必填 mimeType 与无前缀 Base64 data。示例用 PNG、PDF、MP3 或 MP4，编码后完整 JSON 限定小于20 MB；更大素材先压缩或切分。

mimeTypestring
datastring
generationConfigobject

选填，顶层对象。输出长度、采样、结构化格式、思考和语音设置分别放在对象对应子字段。

temperaturenumber
topPnumber
topKinteger
maxOutputTokensinteger

选填，正整数，无统一默认。限制输出 token，思考也占用预算；示例 4096。

stopSequencesarray<string>
元素string

数组元素。

safetySettingsarray<object>

选填字段；是否可用取决于当前模型和协议。

元素object

数组元素。

categorystring
thresholdstring
toolsarray<object>

选填，顶层工具数组。按本页选择 functionDeclarations、googleSearch、urlContext 或 codeExecution；名称区分大小写。

元素object

数组元素。

systemInstructionobject

选填，顶层。parts 中填写文本指令，不放入 generationConfig。

partsarray<object>
元素object

数组元素。

路径、查询与 Header 参数

参数位置类型必填说明示例
Content-TypeHeaderstring否-application/json
Response

返回响应 200

HTTP 响应
响应 200json
响应 200object
embeddingsobject

批量嵌入文档

改用 batchEmbedContents，每一项包含模型、内容和任务类型。下面演示两条文档；不是厂商离线 Batch 作业。

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

payload = json.loads(r'''{
  "requests": [
    {
      "model": "models/gemini-embedding-001",
      "content": {
        "parts": [
          {
            "text": "如何重置密码？"
          }
        ]
      },
      "taskType": "RETRIEVAL_DOCUMENT",
      "outputDimensionality": 768
    },
    {
      "model": "models/gemini-embedding-001",
      "content": {
        "parts": [
          {
            "text": "如何修改邮箱？"
          }
        ]
      },
      "taskType": "RETRIEVAL_DOCUMENT",
      "outputDimensionality": 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/v1beta/models/gemini-embedding-001:batchEmbedContents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

常见错误与参考

output_dimensionality 是 SDK 风格名称，REST 正文用 outputDimensionality。不得在 batchEmbedContents 外层用 contents 数组替代 requests。

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

Google 官方 generateContent 示例。