`POST https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal` 将视频、图像和文本转化为向量，用于以图搜图、语义检索、跨模态匹配等场景。 ## 鉴权本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](https://ark.volcengine.com/region:cn-beijing/docs/82379/1298459?lang=zh)。 * API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。 --- ## 请求参数 ### Body 参数 **input** `object[]` `必选` | 输入内容需要向量化的内容列表。列表元素支持文本信息、图片信息以及视频信息。不同模型的支持情况不同 **type** `string` `必选` | 类型 `input.type` 输入内容的类型。取值范围：`text`、`image_url`、`video_url` **image_url** `object` | 图片对象 `input.image_url` 输入给模型的图片对象。当 `type` 为 `image_url` 时必填 **url** `string` `必选` | 图片地址 `input.image_url.url` 图片信息，可以是图片 URL 或图片 Base64 编码。图片 URL：请确保图片 URL 可被访问。Base64 编码：请遵循格式 `data:image/{图片格式};base64,{图片Base64编码}` **text** `string` | 文本内容 `input.text` 输入给模型的文本内容。当 `type` 为 `text` 时必填。单条文本以 utf\-8 编码，长度不超过模型的最大输入 token 数 **video_url** `object` | 视频对象 `input.video_url` 输入给模型的视频对象。当 `type` 为 `video_url` 时必填

注意

传入视频需要满足以下条件：

格式：.mp4、.avi、.mov，视频格式需小写。

传入 Base64 编码时使用：Base64 编码输入。

单视频文件需在 50MB 以内。

暂不支持对视频文件中的音频信息进行理解。

视频自定义抽帧参数说明：

视频自定义抽帧参数 fps、max_video_tokens、min_frame_tokens、max_frame_tokens、min_frames 均为可选参数。

仅 doubao\-embedding\-vision\-251215 及后续版本支持这些参数。

这些字段不传时，会根据模型对应的抽帧策略使用默认值。

抽帧策略会综合这些参数协同生效：按 fps 抽帧后，每帧按 max_frame_tokens 控制 token 上限，总 token 数不超过 max_video_tokens，实际抽帧数不低于 min_frames。

抽帧数量会直接影响视频 embedding 的 token 消耗，但并非帧数越多效果越好；若单帧 token 过少，视频 embedding 质量也会下降。

建议结合 max_video_tokens 与 min_frame_tokens 进行权衡，在控制总 token 消耗的同时，保证单帧保留足够信息。

当视频时长极短且 fps 过低，导致抽帧后实际帧数为 0 时，会以 min_frames 兜底，保证至少有帧送入编码器。

**url** `string` `必选` | 视频地址 `input.video_url.url` 支持传入视频链接或视频的 Base64 编码 **fps** `number` | 抽帧帧率 `input.video_url.fps` 每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，token 花费少，速度更快。该参数会直接影响视频 embedding 的抽帧数量与 token 消耗 **取值范围**：`[0.2, 5]` **max_frame_tokens** `integer` | 单帧最大 tokens 数 `input.video_url.max_frame_tokens` 单帧最大 tokens 数，用于控制单帧质量的上限。值越大，允许对单帧保留更多的细节；该参数会与 max_video_tokens 一起控制单帧和整体的 token 消耗。且必须大于等于 min_frame_tokens **取值范围**：`[128, 640]` **max_video_tokens** `integer` | 视频最大 tokens 数 `input.video_url.max_video_tokens` 视频最大 tokens 数，值越大保留的视频信息越多。该参数用于控制视频抽帧后最多送入模型的 token 数；超过此值时，会按帧数上限截断 **取值范围**：`[10240, 204800]` **min_frame_tokens** `integer` | 单帧最小 tokens 数 `input.video_url.min_frame_tokens` 单帧最小 tokens 数，用于控制单帧压缩的下限。值越小，允许对单帧进行更大的压缩，但单帧细节下降；若单帧 token 过少，也会影响最终向量表征质量 **取值范围**：`[16, 128]` **min_frames** `integer` | 最小抽帧数 `input.video_url.min_frames` 最小抽帧数，用于保证短视频具备足够的处理帧数。若 fps 字段抽帧总数小于 min_frames，则优先按照 min_frames 配置要求抽帧，以避免极短视频抽不到帧 **取值范围**：`[5, 16]` **model** `string` `必选` | 模型 ID 您需要调用的模型的 ID（Model ID），开通模型服务，并查询 Model ID。您也可通过 Endpoint ID 来调用模型，获得限流、计费类型、运行状态查询、监控、安全等高级能力 **dimensions** `integer` `默认值 2048` | 向量维度用于指定输出的向量维度。取值范围：`1024` 或 `2048`。 **encoding_format** `string` `默认值 float` | 返回格式 embedding 返回的格式。取值范围：`float`、`base64`、`null`。 **instructions** `string` | 推理提示词推理提示词，用户传入时直接使用，未传入时按输入模态生成默认值 **multi_embedding** `object` | 多向量配置多向量（multi\-vector）输出配置，控制是否输出多向量及其压缩方式。开启后，每个输入除返回稠密向量外，额外返回一组 token 级别的向量（二维数组）

注意

不允许传入空对象 {}，需要至少包含 type 字段。

compression 与 encoding_format 正交，可独立设置：

encoding_format 控制稠密向量返回格式（float / base64 / null）。

compression 控制 multi_embedding 字段的压缩格式（blosc2 / zstd / 不传）。

当 type=disabled 时，compression 字段会被忽略。

**compression** `string` | 多向量压缩 `multi_embedding.compression` 多向量压缩方式（可选）。仅在 `type=enabled` 时生效： * `blosc2`：使用 `blosc2` 压缩； * `zstd`：使用 `zstd` 压缩；不传或留空则不压缩 **type** `string` `默认值 disabled` | 多向量开关 `multi_embedding.type` 多向量输出开关： * `disabled`：不输出多向量 * `enabled`：在稠密向量基础上额外返回 data.multi_embedding。 **sparse_embedding** `object` | 稀疏向量开关稀疏向量开关配置，仅纯文本输入支持配置此字段 **type** `string` `默认值 disabled` | 稀疏向量开关 `sparse_embedding.type` 用于控制是否输出稀疏向量： * `disabled`：仅输出稠密向量 * `enabled`：同时输出稠密向量和稀疏向量。 ## 响应参数 **created** `integer` | 创建时间本次请求创建时间的 Unix 时间戳（秒） **data** `object` | 向量化结果向量化结果列表，与 `input` 中的元素一一对应 **embedding** `number[] / string` | 稠密向量 `data.embedding` 稠密向量结果（dense embedding）。返回 float 数组（`float[]`） **object** `string` | 对象类型 `data.object` 对象类型，固定为 `embedding` **multi_embedding** `number[] / string[]` | 多向量 `data.multi_embedding` 当请求开启多向量时返回的 token 级别向量列表，为二维 float 数组（fp16）；当开启 `compression` 时返回 base64 字符串

注意

当请求带上 compression 时，data.multi_embedding 返回 base64 字符串，使用方需按以下方式解码：

base64 解码得到二进制数据。

数据使用 fp16 精度存储；按 fp16 类型解析。

按 (token_count, embedding_dim) reshape 成二维数组。

不带 compression 时，data.multi_embedding 直接返回二维 float 数组。

**sparse_embedding** `object[]` | 稀疏向量 `data.sparse_embedding` 当请求开启稀疏向量时返回的稀疏向量条目 **index** `integer` | 维度索引 `data.sparse_embedding.index` 非零维度的索引位置 **value** `number` | 维度数值 `data.sparse_embedding.value` 该维度对应的数值 **id** `string` | 请求 ID 本次请求的唯一标识 **model** `string` | 实际使用的模型本次请求实际使用的模型名称和版本 **object** `string` | 对象类型对象类型，固定为 `list` **usage** `object` | token 用量本次请求的 token 用量信息 **prompt_tokens** `integer` | 输入 token 数 `usage.prompt_tokens` 输入消耗的 prompt token 总数 **prompt_tokens_details** `object` | token 用量明细 `usage.prompt_tokens_details` prompt token 用量的细分明细 **image_tokens** `integer` | 图片 token 数 `usage.prompt_tokens_details.image_tokens` 图片输入消耗的 prompt token 数量 **text_tokens** `integer` | 文本 token 数 `usage.prompt_tokens_details.text_tokens` 文本输入消耗的 prompt token 数量 **total_tokens** `integer` | 总 token 数 `usage.total_tokens` 本次请求消耗的 token 总数

火山方舟