Amux AI

Create Embeddings

最近更新:2026年11月22日

OpenAI 兼容向量嵌入端点,支持官方 OpenAI SDK 及 Jina 多模态与任务适配器扩展参数。

兼容 OpenAI 协议的向量嵌入端点。使用官方 openai Python 或 TypeScript SDK 时,只需将 base_url 指向 Amux AI 并携带 Authorization: Bearer <key> 即可直接调用。

本页定义通用 POST /v1/embeddings 协议结构(Jina AI 等遵循 OpenAI 嵌入路径的模型均复用本端点)。各模型在上下文长度、默认维度、Matryoshka 截断范围、任务适配器及多模态输入格式上的差异,请参阅「向量」分区的模型文档,例如 Jina Embeddings v5 Text Small、Jina Embeddings v5 Omni Small、Jina Embeddings v4 与 Jina Embeddings v3。

POSThttps://gateway.amux.ai/v1/embeddings

鉴权

header
Authorizationstring必填

Bearer <你的 Amux AI 密钥> 在控制台创建的 Amux AI API 密钥。

Content-Typestring必填默认 "application/json"

固定为 application/json。

请求

application/json
modelstring必填

模型规范 ID 或别名(如 jina/jina-embeddings-v5-text-small 或 jina-embeddings-v5-text-small)。

inputstring | object | array<string | object>必填

待嵌入的文本字符串、单个多模态对象(Jina PDF 文档 { pdf } 须单独提交,不可放入数组)、字符串数组、token ID 数组,或多模态对象数组(支持 { text }、{ image }、{ audio }、{ video } 及 V5 Omni 的融合分组 { content: [...] })。

dimensionsinteger

可选的输出向量维度(Matryoshka 截断),支持范围因模型而异(v5 Small / v3 为 1–1024,v5 Nano 为 1–768,v4 为 1–2048)。

encoding_format"float" | "base64"

OpenAI 兼容的输出向量编码格式(float 或 base64)。

embedding_type"float" | "base64" | "binary" | "ubinary" | array<"float" | "base64" | "binary" | "ubinary">

Jina 输出向量精度或量化格式(float、base64、binary、ubinary,或由其组成的数组)。

task"retrieval.query" | "retrieval.passage" | "text-matching" | "clustering" | "classification" | "separation" | "code.query" | "code.passage"

可选的任务适配器标识。各模型支持子集不同(v5 支持 clustering;v3 支持 separation;v4 支持 code.query / code.passage),详见各模型文档。

normalizedboolean

是否返回经 L2 归一化的单位向量(v5 / v3 默认 true;v4 不提供该参数)。

truncateboolean

输入超出模型上下文上限时是否自动截断,而非返回错误(默认 false)。

late_chunkingboolean

是否启用批内 Late Chunking(仅 v4 文本输入与 v3 支持,v5 不提供该参数)。

return_multivectorboolean

是否返回 token 级多向量表示(仅 jina-embeddings-v4 支持,且不可与 dimensions 同时使用)。

return_tokenized_inputboolean

是否随多向量结果返回分词序列(仅 jina-embeddings-v4 且 return_multivector=true 时生效)。

userstring

可选的终端用户标识,用于监控与风控。

响应

200response

向量嵌入生成成功。

400response

请求体格式错误、传入不支持的流式开关,或目标模型不支持嵌入端点。

402response

工作区账户余额不足。

协议特性说明

  • 同步非流式:嵌入端点不支持流式输出,传入 stream: true 将返回 400 错误。
  • 扩展参数直连透传:除标准 OpenAI 字段(model、input、dimensions、encoding_format、user)外,网关直接透传厂商扩展参数(如 Jina 的 task、embedding_type、normalized、truncate、late_chunking、return_multivector、return_tokenized_input,以及单个多模态对象 { pdf } 或多模态对象数组与 V5 Omni 融合分组 { content: [...] })。
  • 多模态用量计费:多模态嵌入请求的 usage.total_tokens 聚合了文本(prompt_tokens)与图像/PDF(image_tokens)、音频(audio_tokens)、视频(video_tokens)全部输入 token,平台按 total_tokens 统一结算,无输出 token 费用。
  • 端点隔离:嵌入模型不支持通过 /v1/chat/completions、/v1/messages 等文本对话端点调用。
  • 体积限制:单次请求体上限 32 MB,单次响应体上限 32 MB(大批量高维向量建议按批次切分或使用 base64 编码)。

错误处理

错误响应统一采用 OpenAI 标准错误结构。上游校验失败(包括 FastAPI 422)将映射为 400 invalid_request 并保留具体字段报错;请求体超限时返回 400 且不会触发跨渠道重试。完整错误类型见错误与重试。

cURL
curl https://gateway.amux.ai/v1/embeddings \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina/jina-embeddings-v5-text-small",
    "input": [
      "Organic skincare for sensitive skin with aloe vera and chamomile."
    ]
  }'
{
  "object": "list",
  "model": "jina/jina-embeddings-v5-text-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14,
    "image_tokens": 0,
    "audio_tokens": 0,
    "video_tokens": 0
  }
}