You need to enable JavaScript to run this app.
导航
火山方舟大模型服务平台
  • 文档首页
    • /火山方舟大模型服务平台/API 参考/向量化 API/图文向量化 API
图文向量化 API
最近更新时间：2025.02.19 22:10:00首次发布时间：2025.01.15 20:28:15
我的收藏
POST https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal

Doubao-embedding-vision 图文向量化模型是一款字节跳动研发的图文向量化模型，是一种支持文本、图片及图文混合输入的向量化技术，适用于文搜图、图搜图、图文混合搜索等场景。

鉴权方式

本接口支持 API Key 鉴权方式，详见鉴权认证方式。

使用限制

图片格式说明

支持的图片格式如下表，需注意文件后缀和图片格式需要匹配，即图片文件扩展名（URL 传入）、编码中图片格式声明（Base64 编码传入）需要与图片实际信息一致。

图片格式

文件扩展名

内容格式 Content Type

JPEG

.jpg, .jpeg

image/jpeg

PNG

.apng, .png

image/png

GIF

.gif

image/gif

WEBP

.webp

image/webp

BMP

.bmp

image/bmp

TIFF

.tiff, .tif

image/tiff

ICO

.ico

image/x-icon

DIB

.dib

image/bmp

ICNS

.icns

image/icns

SGI

.sgi

image/sgi

JPEG2000

.j2c, .j2k, .jp2, .jpc, .jpf, .jpx

image/jp2

说明

TIFF、 SGI、ICNS、JPEG2000 几种格式图片，需要保证和元数据对齐如在对象存储中正确设置文件元数据，否则会解析失败。

图片尺寸说明

图片尺寸需要同时满足以下条件，否则会返回错误信息InvalidImageURL(****) 。

  • 图片的宽和高的长度取值范围：[10, 6000] px。
  • 图片的宽高比（即宽/高）取值范围：[1/100, 100]。

例如：当图片宽高的长度为798 px、7000 px，图片高的长度大于6000 px，则会返回错误信息InvalidImageURL('height or width exceed max_total_pixels, 798 or 7000 > 6000') 。

请求参数

请求体

参数名称

类型

是否必填

描述

示例值

默认值

model

String

是

本次请求使用模型的 Model ID，或者使用已配置的向量化模型的推理接入点 (Endpoint ID)。

doubao-embedding-vision-241215
或
ep-202406040*****-*****

input

Array of Input

是

需要向量化的内容列表。注意：

  • type 可为text、image_url，且每种类型最多1个

注意

在处理不同类型的输入内容（包括纯文本、纯图片以及图文混排）时，系统会生成一定数量的文本 tokens（约 20 个）以辅助模型完成推理任务。

参见 Input

encoding_format

String

否

embedding 返回的格式，可为 float或base64。

float

float

数据结构

Input

参数名称

类型

是否必填

描述

示例值

type

String

是

支持text 或 image_url，传入的信息类型。

  • 传入信息为文本信息设置为text。
  • 传入信息为图片信息设置为image_url。

text

String

条件必填

当tpye设置为text时，输入文本信息。

  • 单条文本以 utf-8 编码，长度不超过 100,000 字节。
  • 单条文本不超过模型的最大输入 token 数为 8k。
"input":[
    {
        "type":"text",
        "text":"海很深"
     },
   ],//文

image_url

Object

当tpye设置为image_url时，输入图片信息。

  • url [String]：必选，支持传入图片URL或图片Base64编码。
    • 传入图片URL：需确保图片URL可被访问。
    • 传入Base64编码：请遵循格式data:image/{图片格式};base64,{Base64编码}：
      • {图片格式}：支持多种格式，参见下面的图片要求。
      • {Base64编码}：图片的Base64编码。
    • 图片要求： 
"input":[
    {
        "type":"image_url",
        "image_url":{
            "url":"https://***.******.***/***.jpeg"
         }
     }
   ]//图

响应参数

请求响应

参数名称

类型

描述

示例值

id

String

本次请求的唯一标识

021718049470528d92fcbe0865fdffdde********************

model

String

本次请求实际使用的模型名称和版本

doubao-embedding-text-240515

created

Integer

本次请求创建时间的 Unix 时间戳（秒）

1718049470

object

String

固定为 list

list

data

Embedding

本次请求的算法输出内容

usage

Usage

本次请求的 tokens 用量

数据结构

Embedding

参数名称

类型

描述

示例值

embedding

Array of Float

对应内容的向量化结果

[0.62109375,-0.69140625,...,0.38671875]

object

String

固定为 embedding

embedding

Usage

参数名称

子字段

类型

描述

示例值

prompt_tokens

-

Integer

输入的 prompt token 数量

2670

total_tokens

-

Integer

本次请求消耗的总 token 数量（输入 + 输出）

2670

prompt_tokens_details

输入的 prompt token使用情况的细节信息

text_tokens

Integer

输入的 prompt token中用于文本的token数量

说明

为保证模型效果，当图片传入时，系统会生成少量的预设 text_tokens，可能会产生额外的 text_tokens 用量

1024

image_tokens

Integer

输入的 prompt token中用于图片的token数量

1646

请求示例
curl https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ea764f0f-3b60-45b3-****-************" \
  -d '{
    "model": "doubao-embedding-vision-241215",
    "input": [
        {
            "type":"text",
            "text":"天很蓝，海很深"
        },
        {    
            "type":"image_url",
            "image_url":{
                "url":"https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"
            }
        }
      ]
}'

响应示例
{
    "id": "021718067849899d92fcbe0865fdffdde********************",
    "created": 171806****,
    "object": "list",
    "model": "doubao-embedding-***-******",
    "data": [
        {
            "object": "embedding",
            "embedding": [[0.62109375,-0.69140625,...,0.38671875]
        }
    ],
    "usage": {
        "prompt_tokens": 1340,
        "total_tokens": 1340,
        "prompt_tokens_details": {
            "text_tokens": 1312,
            "image_tokens": 28
        }
    }
}

错误处理

错误响应

本接口调用失败的返回结构和参数释义请参见返回结构文档。

错误码

本接口错误码请参见公共错误码文档。