多模态向量化 API
当您需通过语义来处理视频、图像和文本，如以图搜图、语义检索等，可以调用多模态向量化服务，将视频、图像和文本转化为向量，来分析其语义关系。本文为您提供接口的参数详细说明供您查阅。
POST https://ai-tokenhub.com/api/v3/embeddings/multimodal
请求参数
请求信息
| 项 | 值 |
|---|---|
| 请求方法 | POST |
| 官方请求地址 | https://ai-tokenhub.com/api/v3/embeddings/multimodal |
| Content-Type | application/json |
| 鉴权方式 | API Key 鉴权（Bearer Token） |
请求头
| 字段名 | 必填 | 说明 |
|---|---|---|
| Authorization | ✓ | 格式: Bearer <$YOUR_API_KEY>，其中 <$YOUR_API_KEY> 为您在天枢平台获取的 API 密钥 |
| Content-Type | ✓ | 固定值: application/json |
请求体
model string 必选
您需要调用的模型的 ID（Model ID）。
input object[] 必选
需要向量化的内容列表。列表元素支持文本信息和图片信息以及视频信息。
文本信息 object
输入给模型转化为向量的内容，文本内容部分。
input.type string 必选
输入内容的类型，此处应为 text。
input.text string 必选
输入给模型的文本内容。单条文本以 utf-8 编码，长度不超过模型的最大输入 token 数。
图片信息 object
输入给模型转化成向量的内容，图片信息部分。
input.type string 必选
输入内容的类型，此处应为 image_url。
input.image_url object 必选
输入给模型的图片对象。
input.image_url.url string 必选
图片信息，可以是图片 URL 或图片 Base64 编码。
- 图片 URL：请确保图片 URL 可被访问。
- Base64 编码：请遵循此格式
data:image/{图片格式};base64,{图片Base64编码}。
视频信息 object
输入给模型转化成向量的内容，视频信息部分。
- 格式：
.mp4、.avi、.mov，视频格式需小写。 - 单视频文件需在 50MB 以内。
- 暂不支持对视频文件中的音频信息进行理解。
input.type string 必选
输入内容的类型，此处应为 video_url。
input.video_url object 必选
输入给模型的视频对象。
input.video_url.url string 必选
支持传入视频链接或视频的 Base64 编码。
input.video_url.fps number
取值范围：[0.2, 5]。每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。
input.video_url.max_video_tokens integer
取值范围：[10240, 204800]。视频最大 tokens 数，值越大保留的视频信息越多。超过此值时，会按帧数上限截断。
input.video_url.min_frame_tokens integer
取值范围：[16, 128]。单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降。
input.video_url.max_frame_tokens integer
取值范围：[128, 640]，且必须大于等于 min_frame_tokens。单帧最大 tokens 数，用于控制单帧质量的上限。
input.video_url.min_frames integer
取值范围：[5, 16]。最小抽帧数，用于保证短视频具备足够的处理帧数。
- 视频自定义抽帧参数
fps、max_video_tokens、min_frame_tokens、max_frame_tokens、min_frames均为可选参数。 - 这些字段不传时，会根据模型对应的抽帧策略使用默认值。
- 抽帧策略会综合这些参数协同生效：按
fps抽帧后，每帧按max_frame_tokens控制 token 上限，总 token 数不超过max_video_tokens，实际抽帧数不低于min_frames。 - 抽帧数量会直接影响视频 embedding 的 token 消耗，但并非帧数越多效果越好；若单帧 token 过少，视频 embedding 质量也会下降。
encoding_format string / null
默认值 float。取值范围：float、base64、null。embedding 返回的格式。
dimensions integer
默认值 2048。取值范围：1024 或 2048。用于指定输出的向量维度。
instructions string
推理提示词，用户传入时直接使用，未传入时按输入模态生成默认值。
sparse_embedding object
稀疏向量开关配置，仅纯文本输入支持配置此字段。
sparse_embedding.type string
默认值 disabled。取值范围：enabled、disabled。用于控制是否输出稀疏向量。
disabled：仅输出稠密向量。enabled：同时输出稠密向量和稀疏向量。
multi_embedding object
多向量（multi-vector）输出配置，控制是否输出多向量及其压缩方式。开启后，每个输入除返回稠密向量外，额外返回一组 token 级别的向量（二维数组）。
multi_embedding.type string
默认值 disabled。取值范围：enabled、disabled。多向量输出开关。
type="disabled"：不输出多向量。type="enabled"：在稠密向量基础上，额外返回data.multi_embedding。
multi_embedding.compression string
多向量的压缩方式，仅在 type="enabled" 时生效。传入后，data.multi_embedding 会返回压缩并 base64 编码后的字符串，可显著降低传输体积，客户端需按解码协议还原。
取值范围：blosc2、zstd。
blosc2：专门为数字数组优化的，同样的向量能压得更小、更省带宽。zstd：通用高速压缩方式，几乎所有语言都有现成解码库，接入简单、解压快。
multi_embedding.type="disabled"时，compression字段会被忽略。multi_embedding.type="enabled"且compression不传时，表示返回未压缩的二维数组。multi_embedding可以与sparse_embedding同时开启，但sparse_embedding仍仅支持纯文本输入。multi_embedding不允许传空对象{}，否则会返回 400MissingParameter。
响应参数
id string
本次请求的唯一标识。
model string
本次请求实际使用的模型名称和版本。
created integer
本次请求创建时间的 Unix 时间戳（秒）。
object string
固定为 list。
data object
本次请求的算法输出内容。
data.embedding float[]
对应内容的向量化结果。
data.sparse_embedding array
稀疏向量，仅 sparse_embedding.type="enabled" 时返回。每个成员为 {"index": 维度索引, "value": 非零值} 结构，仅返回非零元素。
data.multi_embedding float[][] / string
多向量，仅 multi_embedding.type="enabled" 时返回。
- 未开启压缩时，返回
float[][]，外层表示 token 维度，内层表示每个 token 的子向量。 - 开启
compression=blosc2/zstd时，返回经过压缩并 Base64 编码后的字符串。
- 当
data.multi_embedding以压缩字符串返回时，客户端应按以下规则解码： - 1. 对返回的 Base64 字符串进行解码，并按
compression指定的算法解压。 - 2. 将解压后的二进制数据按
fp16（2 字节，小端序）解析为一维数组。 - 3. 按
[num_tokens, dimensions]将一维数组重塑为二维数组。 - 压缩返回场景下，响应不会单独返回
shape或dtype字段。
data.object string
固定为 embedding。
usage object
本次请求的 token 用量。
usage.prompt_tokens integer
输入内容 token 数量。
usage.total_tokens integer
本次请求消耗的总 token 数量（输入 + 输出）。
usage.prompt_tokens_details object
输入的内容使用 token 量的细节信息。
usage.prompt_tokens_details.text_tokens integer
输入内容中，文本内容对应的 token 量，以及视频内容时间轴产生的 token 量。为保证模型效果，当图片或视频传入时，会生成少量的预设文本 token，产生额外的 text_tokens。
usage.prompt_tokens_details.image_tokens integer
输入内容中，图片内容以及视频内容抽帧图片对应的 token 量。