部分大模型具备图片视觉理解能力，支持本地文件和图片 URL 方式传入图片，适用于图片描述、分类、视觉定位等场景。 :::tip 方舟平台的新用户？获取 API Key 及开通模型等准备工作，请参见 [快速入门](/docs/82379/1399008)。 ::: # 快速开始通过图片 URL 方式传入模型快速体验图片理解效果，Responses API 示例代码如下。 |输入 |输出预览 | |---|---| |![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e3b9829615f54bb88a91892e2b3fb1a3~tplv-goo7wpa0wc-image.image =1798x) |* 思考：用户现在需要找支持输入图片的模型系列，看表格里的输入列中的图片那一行。表格里模型系列Doubao\-Seed\-1.8对应的输入图片列是√，其他DeepSeek\-V3.2和GLM\-4.7对应的输入图片都是×，所以答案应该是Doubao\-Seed\-1.8。|\ |> 支持输入图片的模型系列是哪个？ |* 回答：支持输入图片的模型系列是Doubao\-Seed\-1.8。 | ```mixin-react return ( ); ``` # 模型与API 支持的模型： * 请参见[视觉理解能力](/docs/82379/1330310#ff5ef604)。支持的 API： * [Responses API](https://www.volcengine.com/docs/82379/1569618)：支持图片作为输入进行分析。支持文件路径上传进行图片理解，使用方式参见[文件路径上传（推荐）](/docs/82379/1362931#2c38c01b)。 * [Chat API](https://www.volcengine.com/docs/82379/1494384)：支持图片作为输入进行分析。 # 图片传入方式支持的图片传入方式如下： * 本地文件上传： * [文件路径上传（推荐）](/docs/82379/1362931#2c38c01b)：直接传入本地文件路径，文件大小不能超过 512 MB。 * [Base64 编码传入](/docs/82379/1362931#477e51ce)：适用于图片文件体积较小的场景，单张图片小于 10 MB，请求体不能超过 64 MB。 * [图片 URL 传入](/docs/82379/1362931#d86010f4)：适用于图片文件已存在公网可访问 URL 的场景，单张图片小于 10 MB。 :::tip Chat API 是无状态的，如需模型对同一张图片进行多轮理解，则每次请求时都需传入该图片信息。 ::: ## 本地文件上传 ### 文件路径上传（推荐）建议优先采用文件路径方式上传本地文件，该方式可以支持最大 512MB 文件的处理。（当前 Responses API 支持该方式）直接向模型传入本地文件路径，会自动调用 Files API 完成文件上传，再调用 Responses API 进行图片分析。仅 Python SDK 和 Go SDK 支持该方式。具体示例如下： > * 如果需要实时获取分析内容，或者要规避复杂任务引发的客户端超时失败问题，可采用流式输出的方式，使用方式可参见[示例代码](/docs/82379/2123275#9346c907)。 > * 支持直接使用 Files API 上传本地文件，具体请参见[文件输入(File API)](/docs/82379/1885708)。 ```mixin-react return ( ); ``` ### Base64 编码传入将本地文件转换为 Base64 编码字符串，然后提交给大模型。该方式适用于图片文件体积较小的情况，单张图片小于 10 MB，请求体不能超过 64MB。（Responses API 和 Chat API 都支持该方式。） :::warning 将图片文件转换为Base64编码字符串，然后遵循`data:{mime_type};base64,{base64_data}`格式拼接，传入模型。 * `{mime_type}`：文件的媒体类型，需要与文件格式mime_type对应。支持的图片格式详细见[图片格式说明](/docs/82379/1362931#51efc45f)。 * `{base64_data}`：文件经过Base64编码后的字符串。 ::: |[Chat API](https://www.volcengine.com/docs/82379/1494384) |[Responses API](https://www.volcengine.com/docs/82379/1569618) | |---|---| |```Python|```Python|\ |...|...|\ |model="doubao-seed-2-0-lite-260215",|model="doubao-seed-2-0-lite-260215",|\ |messages=[|input=[|\ | {| {|\ | "role": "user",| "role": "user",|\ | "content": [| "content": [|\ | {| {|\ | "type": "image_url",| "type": "input_image",|\ | "image_url": {| "image_url": f"data:image/png;base64,{base64_image}"|\ | "url": f"data:image/png;base64,{base64_image}"| },|\ | }| {|\ | },| "type": "input_text",|\ | {| "text": "Which model series supports image input?"|\ | "type": "text",| }|\ | "text": "Which model series supports image input?"| ]|\ | }| }|\ | ]|]|\ | }|...|\ |]|```|\ |...| |\ |```| |\ | | | * Responses API 示例代码： ```mixin-react return ( ); ``` * Chat API 示例代码： ```mixin-react return ( ;base64,{base64_image}： # PNG图片："url": f"data:image/png;base64,{base64_image}" # JPEG图片："url": f"data:image/jpeg;base64,{base64_image}" # WEBP图片："url": f"data:image/webp;base64,{base64_image}" "url": f"data:image/;base64,{base64_image}" }, }, { "type": "text", "text": "Which model series supports image input?", }, ], } ], ) print(completion.choices[0]) \`\`\` `}> messagesForReqList = new ArrayList<>(); // 本地图片路径（替换为实际路径） String imagePath = "demo.png"; // 生成Base64数据URL String base64Data = "data:image/png;base64," + encodeImage(imagePath); // 构建消息内容（修复内容部分构建方式） List contentParts = new ArrayList<>(); // 图片部分使用builder模式 contentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL(base64Data)) .build()); // 文本部分使用builder模式 contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("Which model series supports image input?") .build()); // 创建消息 messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ## 图片 URL 传入如果图片已存在公网可访问URL，可以在请求中直接填入图片的公网URL，单张图片不能超过 10 MB。（Responses API 和 Chat API 都支持该方式。） :::tip 如果使用 URL，建议使用火山引擎TOS（对象存储）存储图片并生成访问链接，不仅能保证图片的稳定存储，还能利用方舟与TOS的内网通信优势，有效降低模型回复的时延和公网流量费用。 ::: |[Chat API](https://www.volcengine.com/docs/82379/1494384) |[Responses API](https://www.volcengine.com/docs/82379/1569618) | |---|---| |```Python|```Python|\ |...|...|\ |model="doubao-seed-2-0-lite-260215",|model="doubao-seed-2-0-lite-260215",|\ |messages=[|input=[|\ | {| {|\ | "role": "user",| "role": "user",|\ | "content": [| "content": [|\ | {| {|\ | "type": "image_url",| "type": "input_image",|\ | "image_url": {| "image_url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png"|\ | "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png"| },|\ | }| {|\ | },| "type": "input_text",|\ | {| "text": "Which model series supports image input?"|\ | "type": "text",| }|\ | "text": "Which model series supports image input?"| ]|\ | }| }|\ | ]|]|\ | }|...|\ |]|```|\ |...| |\ |```| |\ | | | * Responses API 示例代码：[快速开始](/docs/82379/1362931#18cf565a) * Chat API 示例代码： ```mixin-react return ( messagesForReqList = new ArrayList<>(); // Construct the content of the message List contentParts = new ArrayList<>(); // Use builder mode for the image contentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png")) .build()); // Use builder mode for text contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("Which model series supports image input?") .build()); // Create message messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` # 使用场景 ## 多图输入 API 可支持接受和处理多个图像输入，这些图像可通过图片可访问 URL 或图片转为 Base64 编码后输入，模型将结合所有传入的图像中的信息来回答问题。 * Responses API 示例代码： ```mixin-react return ( ); ``` * Chat API 示例代码： ```mixin-react return ( messagesForReqList = new ArrayList<>(); // Construct content of the message List contentParts = new ArrayList<>(); // Use builder mode for the first image contentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png")) .build()); // contentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_2.png")) .build()); contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("支持输入图片的模型系列是哪个？同时，豆包应用场景有哪些？") .build()); messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ## 控制图片理解的精细度控制图片理解的精细度（指对画面的精细）： **image_pixel_limit 、detail** 字段，2个字段若同时配置，则生效逻辑如下： * 生效前提：图片像素范围在 [196, 36,000,000] px，否则直接报错。 * 生效优先级：**image_pixel_limit** 高于 **detail** 字段，即同时配置 **detail** 与 **image_pixel_limit** 字段时，生效 **image_pixel_limit** 字段配置。 * 缺省时生效：**image_pixel_limit** 字段的 **min_pixels** / **max_pixels** 字段未设置，则使用 **detail** 默认值配置所对应的值。具体范围参见[通过 detail 字段（图片理解）](/docs/82379/1362931#885d96dc)。下面分别介绍如何通过 **detail** 、 **image_pixel_limit** 控制视觉理解的精度。 ### 通过 detail 字段（图片理解）通过`detail`参数来控制模型理解图片的精细度，不同模型支持的 detail 模式、token 用量、图片像素区间如下： :::tip doubao\-seed\-2.0 模型 detail 默认值为 `high`，单图固定 1280 个 tokens，在不牺牲效果的同时消耗的 tokens 更少。 ::: |detail模式 |doubao\-seed\-1.8 之前的模型||doubao\-seed\-1.8 模型||doubao\-seed\-2.0 模型||\ | |> detail 默认值为`low` | |> detail 默认值为 `high` | |> detail 默认值为 `high` | | |^^|单图token范围 |图片像素区间 |单图token范围 |图片像素区间 |单图token范围 |图片像素区间 | |---|---|---|---|---|---|---| |low |[4, 1312] |[3136, 1048576] |[1, 1213] |[1764, 2139732] |[1, 1280] |[1764, 2257920] | |high |[4, 5120] |[3136, 4014080] |[1, 5120] |[1764, 9031680] |1280 |2257920 | |xhigh |\- |\- |\- |\- |[1280, 5120] |[2257920, 9031680] | * detail 为 `low` 时，图片处理速度会提高，适合图片本身细节较少或者只需模型理解图片大致信息或者对速度有要求的场景。 * detail 为 `high` 或 `xhigh` 时，模型可感知图片更多的细节，但是图片处理速度会降低，适合图像像素值高且需关注细节信息的场景，如街道地图分析等。 **图片缩放规则**：不在指定模式对应的图片像素区间时，方舟会等比例缩放至范围内。 * Responses API 示例代码： ```mixin-react return ( ); ``` * Chat API 示例代码： ```mixin-react return ( messagesForReqList = new ArrayList<>(); List contentParts = new ArrayList<>(); contentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png","high")) .build()); contentParts.add(ChatCompletionContentPart.builder() .type("text") .text("Which model series supports image input?") .build()); messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(contentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID . .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ### **通过 image_pixel_limit 结构体** 控制传入给方舟的图像像素大小范围，如果不在此范围，则会等比例放大或者缩小至该范围内，后传给模型进行理解。你可通过 **image_pixel_limit** 结构体，精细控制模型可理解的图片像素多少。对应结构体如下： ```Bash "image_pixel_limit": { "max_pixels": 3014080, # 图片最大像素 "min_pixels": 3136 # 图片最小像素 } ``` 示例代码如下： > Java SDK、 Go SDK 不支持此字段。 * Responses API 示例代码： ```mixin-react return ( ); ``` * Chat API 示例代码： ```mixin-react return ( ); ``` ## 图文混排支持灵活地传入提示词和图片信息的方式，你可任意调整传入图片和文本的顺序，以及在`system message`或者`User message`传入图文信息。模型会根据顺序返回处理信息的结果，示例如下。 :::tip 图文混排场景，图文顺序可能影响模型输出效果，若结果不符预期，可调整顺序。当多图+一段文字时，建议将文字放在图片之后。 ::: * Responses API 示例代码： ```mixin-react return ( ); ``` * Chat API 示例代码： ```mixin-react return ( messagesForReqList = new ArrayList<>(); // Build the system message content List systemContentParts = new ArrayList<>(); systemContentParts.add(ChatCompletionContentPart.builder() .type("text") .text("下面人物是目标人物") .build()); systemContentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/target.png")) .build()); systemContentParts.add(ChatCompletionContentPart.builder() .type("text") .text("请确认下面图片中是否含有目标人物") .build()); // Create the system message messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.SYSTEM) .multiContent(systemContentParts) .build()); // Build the user message content List userContentParts = new ArrayList<>(); userContentParts.add(ChatCompletionContentPart.builder() .type("text") .text("图片1中是否含有目标人物") .build()); userContentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/scene_01.png")) .build()); userContentParts.add(ChatCompletionContentPart.builder() .type("text") .text("图片2中是否含有目标人物") .build()); userContentParts.add(ChatCompletionContentPart.builder() .type("image_url") .imageUrl(new ChatCompletionContentPartImageURL( "https://ark-project.tos-cn-beijing.volces.com/doc_image/scene_02.png")) .build()); // Create user message messagesForReqList.add(ChatMessage.builder() .role(ChatMessageRole.USER) .multiContent(userContentParts) .build()); ChatCompletionRequest req = ChatCompletionRequest.builder() .model("doubao-seed-2-0-lite-260215") //Replace with Model ID .messages(messagesForReqList) .maxTokens(300) .build(); service.createChatCompletion(req) .getChoices() .forEach(choice -> System.out.println(choice.getMessage().getContent())); // shutdown service after all requests are finished service.shutdownExecutor(); } } \`\`\` `}>); ``` ## 视觉定位（Visual Grounding）请参见教程 [视觉定位 Grounding](/docs/82379/1616136)。 ## GUI任务处理请参见教程 [GUI 任务处理](/docs/82379/1584296)。 # 使用说明 :::tip 处理完图片/视频后，文件会从方舟服务器删除。方舟不会保留你提交的图片、视频以及文本信息等用户数据来训练模型。 ::: ## 图片像素说明 1. 传入图片像素要求如下，超出限制后会直接报错。 * 宽 \> 14px 且高 \> 14px * 宽\*高范围：[196px, 36000000px] * 宽高比范围：[1/150, 150] 2. 图片预处理：根据使用的模型、设置的 detail 模式，将图片等比例缩放至相应的范围（具体见[通过 detail 字段（图片理解）](/docs/82379/1362931#885d96dc)），可降低模型响应时延及 token 消耗。 ## 图片 token 用量说明根据图片宽高像素计算得到 token 用量。不同模型的图片 token 用量估算逻辑如下。单图 token 范围参见[通过 detail 字段（图片理解）](/docs/82379/1362931#885d96dc)。 |doubao\-seed\-1.8 之前的模型 |doubao\-seed\-1.8 模型、doubao\-seed\-2.0 模型 | |---|---| |```JSON|```JSON|\ |min(image_width * image_hight ÷ 784, max_image_tokens)|min(image_width * image_hight ÷ 1764, max_image_tokens)|\ |```|```|\ | | | 以传入模型的单图 token 最大值为 1312 为例，计算图片消耗的 token 数的逻辑如下： * 图片尺寸为 `1280 px × 720 px`：理解这张图消耗的 token 为`1280×720÷784=1176`，该值小于 1312，根据公式计算消耗 token 数为 1176。 * 图片尺寸为 `1920 px × 1080 px`：理解这张图消耗的 token 为`1920×1080÷784=2645`，该值大于 1312，根据公式计算消耗 token 数为 1312。这种情况会对图片进行压缩，即图片会丢失部分细节。譬如字体很小的图片，模型可能会无法识别文字内容。 ## 图片数量说明单次请求传入图片数量受限于模型上下文窗口。当输入过长，触发模型上下文窗口，信息会被截断。 > 模型上下文窗口请参见[模型列表](/docs/82379/1330310)。 > 举例说明： > * 当图片总像素值大，使用的模型上下文窗口为 32k token，每张图片转为 1312 token ，单次请求可传入的图片数量为 `32000 ÷ 1312 = 24`张。 > * 当图片总像素值小，使用的模型上下文窗口为 32k token，每张图片转为 256 token，单次请求可传入的数量为 `32000 ÷ 256 = 125` 张。 :::tip 模型回复的质量，受输入图片信息量影响。过多的图片会导致模型回复质量下滑，请合理控制单次请求传入图片的数量。 ::: ## 图片文件容量使用 URL 方式传入图片，单张图片不能超过 10MB。使用 Base64 编码传入图片，单张图片不能超过 10MB，请求体不能超过 64MB。使用文件路径传入图片，图片不能超过 512 MB。 ## 图片格式说明支持的图片格式如下表，注意文件后缀匹配图片格式，即图片文件扩展名（URL传入时）、图片格式声明（Base64 编码传入时）需与图片实际信息一致。 |**图片格式** |**文件扩展名** |**内容格式** **Content Type** | |---|---|---| |JPEG |.jpg, .jpeg |`image/jpeg` | |PNG |.png |`image/png` | |GIF |.gif |`image/gif` | |WEBP |.webp |`image/webp` | |BMP |.bmp |`image/bmp` | |TIFF |.tiff, .tif |`image/tiff` | |ICO |.ico |`image/ico` | |DIB |.dib |`image/bmp` | |ICNS |.icns |`image/icns` | |SGI |.sgi |`image/sgi` | |JPEG2000 |.j2c, .j2k, .jp2, .jpc, .jpf, .jpx |`image/jp2` | |HEIC |.heic |`image/heic`|\ | | |> doubao\-1.5\-vision\-pro及以后模型支持 | |HEIF |.heif |`image/heif`|\ | | |> doubao\-1.5\-vision\-pro及以后模型支持 | :::tip * 上传文件至对象存储时设置，详情请参见[文档](https://www.volcengine.com/docs/6349/145523#%E8%AE%BE%E7%BD%AE%E6%96%87%E4%BB%B6%E5%85%83%E6%95%B0%E6%8D%AE)。 * 传入 Base64编码时使用：[Base64 编码输入](/docs/82379/1362931#f6222fec)。 * 图片格式需小写。 * TIFF、 SGI、ICNS、JPEG2000 几种格式图片，需保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败，详细请参见 [使用视觉理解模型时，报错InvalidParameter？](/docs/82379/1359411#effccb14) ::: ## API 参数字段说明以下字段视觉理解暂不支持。 * 不支持设置频率惩罚系数，无 **frequency_penalty** 字段。 * 不支持设置存在惩罚系数，**presence_penalty** 字段。 * 不支持为单个请求生成多个返回，无 **n** 字段。 # 常见问题 * [使用视觉理解模型时，报错InvalidParameter？](/docs/82379/1359411#effccb14)

火山方舟