Mafdet AI 帮助中心
English

向量嵌入 (Embeddings)

POST https://api.mafdet.ai/v1/embeddings

用 gemini-embedding-2 把文本转成向量。端点兼容 OpenAI，任意 OpenAI SDK 只需把 base_url 指向 https://api.mafdet.ai/v1 即可使用。

gemini-embedding-2 是文本嵌入模型。图片和视频嵌入请用 multimodal-embedding-1（见下方 图片嵌入、视频嵌入）。音频、PDF 嵌入输入尚未开放。

请求字段

字段类型说明
modelstringgemini-embedding-2
inputstring | string[]单条文本，或文本数组（批量）
dimensionsnumber可选输出维度：768、1536 或 3072（默认 3072）

限制（每次请求）：最多 100 条输入，单条 100,000 字符，总计 2 MB。空输入、 不支持的 dimensions、或任何非字符串元素都会在请求到达模型前被拒绝。

响应字段

字段说明
objectlist
data{ object: "embedding", embedding: number[], index } 数组
usageprompt_tokens / total_tokens（嵌入没有 completion_tokens）

计费

嵌入仅按输入 token 计费——没有生成输出。gemini-embedding-2 售价为 $0.24 / 1M 输入 token（目录实时价见模型总览）。

curl

curl https://api.mafdet.ai/v1/embeddings \
  -H "Authorization: Bearer $MAFDET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-embedding-2",
    "input": "The quick brown fox."
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.mafdet.ai/v1",
    api_key="sk-mafdet-xxxxxxxxxxxxxxxx",
)
resp = client.embeddings.create(
    model="gemini-embedding-2",
    input=["第一段文本", "第二段文本"],
    dimensions=768,
)
print(len(resp.data), "个向量,", len(resp.data[0].embedding), "维")

Node.js

const res = await fetch("https://api.mafdet.ai/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAFDET_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-embedding-2",
    input: "The quick brown fox.",
  }),
});
const data = await res.json();
console.log(data.data[0].embedding.length, "维");

图片嵌入

multimodal-embedding-1 把图片转成 1408 维向量，与其文本嵌入位于同一空间， 用于图片搜索和多模态检索。它是独立于 gemini-embedding-2 的模型，走同一 /v1/embeddings 端点。

每张图片以 data:image/...;base64,... data URI 传入（单个 data URI 字符串， 或数组，最多 8 张）。文本、裸 base64、image_url 对象都会被拒绝——图片只接受 data URI。

# IMAGE=$(base64 -w0 photo.png)
curl https://api.mafdet.ai/v1/embeddings \
  -H "Authorization: Bearer $MAFDET_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"multimodal-embedding-1\",
    \"input\": \"data:image/png;base64,$IMAGE\"
  }"

import base64
from openai import OpenAI

client = OpenAI(base_url="https://api.mafdet.ai/v1", api_key="sk-mafdet-...")
with open("photo.png", "rb") as f:
    uri = "data:image/png;base64," + base64.b64encode(f.read()).decode()
resp = client.embeddings.create(model="multimodal-embedding-1", input=uri)
print(len(resp.data[0].embedding), "维")  # 1408

计费按图片计：multimodal-embedding-1 售价 $0.00012 / 张（1 张 = 1 单位）， 每次请求最多 8 张。错误（400，不计费）：MM_EMBEDDING_NO_IMAGE（无图片 data URI）、 MM_EMBEDDING_MODALITY_NOT_ENABLED（包含非图片项）、MM_EMBEDDING_TOO_MANY_IMAGES。

视频嵌入

multimodal-embedding-1 也能把视频嵌入到同一 1408 维空间。与图片不同，视频用 Vertex 原生形式传入——数组元素 {"video": {"bytesBase64Encoded": "<裸 base64>"}} （裸 base64，不是 data: URI）。provider 按片段返回多个向量。

首发限额（每次请求，分档开放中）：1 个视频、最长 6 秒、最大 300 KB。 体积上限和时长上限同样重要——视频的 base64 会计入你 key 的每分钟 token 上限 （约每 KB 929 token），所以一段很短但高码率的视频同样可能超限。两个上限都在调用模型 之前校验，超限的视频不会产生任何费用。

import base64
from openai import OpenAI

client = OpenAI(base_url="https://api.mafdet.ai/v1", api_key="sk-mafdet-...")
with open("clip.mp4", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
resp = client.embeddings.create(
    model="multimodal-embedding-1",
    input=[{"video": {"bytesBase64Encoded": b64}}],
)
print(len(resp.data), "个向量,", len(resp.data[0].embedding), "维")

计费按秒计：$0.0006 / 秒（视频自身时长，向上取整到整秒）。一段 6 秒的视频 = 6 × $0.0006 = $0.0036。错误（400，不计费）：VIDEO_EMBEDDING_NOT_ENABLED （本部署未开放视频）、MM_EMBEDDING_VIDEO_TOO_LONG（超时长上限）、 MM_EMBEDDING_VIDEO_TOO_LARGE（超体积上限）、 MM_EMBEDDING_VIDEO_UNREADABLE（不是可读 mp4——无法测时长的视频被拒，绝不按 0 计费）、 MM_EMBEDDING_TOO_MANY_VIDEOS。

注意：即使在上述限额内，视频 base64 仍会计入 key 的每分钟 token 上限——300 KB 的视频约合 27.9 万 token。低档套餐的 key 仍可能触发 429；如需嵌入视频，请使用 tpm 上限足够的 key。

错误码

Code含义
EMBEDDING_MODALITY_NOT_ENABLED文本模型收到非文本项（图片请用 multimodal-embedding-1）
EMBEDDING_INPUT_EMPTY空字符串或空数组
EMBEDDING_ITEM_TOO_LONG单条输入超过字符上限
EMBEDDING_BATCH_TOO_LARGE单次超过 100 条输入
EMBEDDING_INPUT_TOO_LARGE输入总字节超过上限
EMBEDDING_DIMENSIONS_INVALIDdimensions 不是 768 / 1536 / 3072 之一

以上都在调用 provider 前返回 400，被拒绝的请求不计费。

后续