# 图像理解
在多媒体内容处理领域，用户经常需要对图片或视频中的视觉信息进行分析和理解。然而，传统的处理方法往往需要复杂的图像处理技术和算法，这不仅增加了开发成本，也提高了技术门槛。部分大模型具备视觉理解能力，如当您传入图片或视频时，大模型可以理解图片或视频里的视觉信息，并结合这些信息完成如描述其中的物体等视觉相关任务。如何利用这些大模型简化多媒体内容的处理流程？
通过这篇教程，您可以学习到如何通过调用大模型API来识别传入图片和视频里的信息，从而降低开发成本和技术门槛。图像理解大模型支持单图或多图的输入，适用于图像描述、视觉问答、物体定位等多种任务，可用于自动化视频内容审核、智能监控分析等，大幅节省人工成本，适用于智能安防、体育赛事分析、媒体内容管理等领域。
#### 计费说明
按Token计费：统计模型进行实时推理服务时消耗的Token数量，按Token数量付费。具体价格请以MaaS控制台为准。详情请见[MaaS图像理解模型](https://support.huaweicloud.com/price-maas/price-maas-0005.html)。
#### 前提条件
- 已在"模型推理 \> 在线推理 \> 预置服务"页签开通预置服务。详情请见[开通MaaS预置服务](https://support.huaweicloud.com/model-call-maas/model-call-052.html)。
- （可选）如果需要控制服务调用流量，可提前创建自定义接入点，详情请参见[MaaS创建自定义接入点](https://support.huaweicloud.com/model-call-maas/model-call-048.html)。

- 已获取API Key。详情请见[在MaaS管理API Key](https://support.huaweicloud.com/model-call-maas/model-call-049.html)。
 
 #### 支持模型
表1支持图像理解的模型列表 
| model参数              | 约束限制                                                                                                                                                                                                                                                                                                                                                                                         | 支持的接口                                                                                                                                                                                                                                                                                                                                                                                                               |
|:---|:---|:---|
| deepseek-v4.1-flash | 上下文长度：1M 最大输入长度：1M 最大输出长度：384K 最大思维链长度：96K 图片限制：图片最大数量600张，单张图片大小不超过32MB，图片分辨率不限制（推荐小于4096\*2160），支持JPEG、PNG、GIF和WebP格式。 上传方式：Base64编码格式或公网可访问的图片地址 | 2 Chat API，接口详情请参考[MaaS标准API V2](https://support.huaweicloud.com/model-call-maas/model-call-019.html)。 OpenAI兼容接口，接口详情请参考[OpenAI兼容接口](https://support.huaweicloud.com/model-call-maas/model-call-021.html)。 Anthropic兼容接口，接口详情请参考[Anthropic兼容接口](https://support.huaweicloud.com/model-call-maas/model-call-022.html)。 |
| qwen2.5-vl-72b     | 上下文长度：48K 最大输入长度：文本48K；图片10MB（Base64编码格式）或者公网可访问的图片地址（单个图片文件的大小不超过10MB）。 最大输出长度：16K                                                                                                                                                                                                           | V1 Chat API，接口详情请参考[MaaS标准API V1](https://support.huaweicloud.com/model-call-maas/model-call-020.html)                                                                                                                                                                                                                                                                                                              |
   
 #### 图片格式说明
支持的图片格式如下表所示，注意文件后缀匹配图片格式，即图片文件扩展名（URL传入时）、图片格式声明（Base64编码传入时）需与图片实际信息一致。
表2支持图片格式 
| **图像格式** | **常见扩展名**            | **MIME Type** |
|:---|:---|:---|
| BMP         | .bmp                | image/bmp      |
| JPEG      | .jpe, .jpeg, .jpg | image/jpeg      |
| PNG        | .png              | image/png     |
| TIFF         | .tif, .tiff        | image/tiff       |
| WEBP      | .webp               | image/webp     |
| GIF        | .gif               | image/gif        |
   
#### 快速开始
支持图像理解的大模型当前支持在请求中传入图片的Base64编码内容或者公网可访问的图片地址，图片信息需要作为用户角色输入信息传给大模型，即"role":"user"，下面是以qwen2.5-vl-72b模型为例，调用模型描述图像内容示例代码，输入图片转为Base64编码格式。
![](https://support.huaweicloud.com/model-call-maas/public_sys-resources/note_3.0-zh-cn.png)
提示词支持图片和文字混排，但图文顺序可能对模型的输出效果产生影响。在提示词构成多张图片+1段文字，建议将文字放在提示词最后。
- [Python]
  ```
  import requests
  import json
  import base64
  #  图片转Base64编码格式
  def encode_image(image_path):
      with open(image_path, "rb") as image_file:
          return base64.b64encode(image_file.read()).decode("utf-8")
  base64_image = encode_image("test.png")
  if __name__ == '__main__':
      url = "https://api.modelarts-maas.com/v1/chat/completions"  # API地址
      api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key
      # Send request.
      headers = {
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {api_key}'
      }
      data = {
          "model": "qwen2.5-vl-72b",  # model参数
          "messages": [
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "text",
                          "text": "描述下图片里的内容"
                      },
                      {
                          "type": "image_url",
                          # 需要注意，Base64，图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
                          # PNG图像：  f"data:image/png;base64,{base64_image}"
                          # JPEG图像： f"data:image/jpeg;base64,{base64_image}"
                          # WEBP图像： f"data:image/webp;base64,{base64_image}"
                          "image_url": {
                              "url": f"data:image/png;base64,{base64_image}"
                          }
                      }
                  ]
              }
          ]
      }
      response = requests.post(url, headers=headers, data=json.dumps(data), verify=False)
      # Print result.
      print(response.status_code)
      print(response.text)
  ```
  模型回复预览：
  ```
  {
      "id": "chatcmpl-4e59963b1117f7fc23836254ef6cf238",
      "object": "chat.completion",
      "created": 1765193821,
      "model": "qwen2.5-vl-72b",
      "choices": [
          {
              "index": 0,
              "message": {
                  "role": "assistant",
                  "reasoning_content": null,
                  "content": "这张图片是一只可爱的柯基犬，它正坐在地上，舌头伸出来，看起来非常开心和友好。背景是户外的地面和一些绿色植物。",
                  "tool_calls": []
              },
              "logprobs": null,
              "finish_reason": "stop",
              "stop_reason": null
          }
      ],
      "usage": {
          "prompt_tokens": 283,
          "total_tokens": 911,
          "completion_tokens": 628,
          "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
  }
  ```
- [Curl]
  ```
  curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{ 
      "model": "qwen2.5-vl-72b",
      "messages": [
        {
          "role": "user",
          "content": [
            {"type": "text", "text": "描述下图片里的内容"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,$BASE64_IMAGE"}}
          ]
        }
      ]
    }'
  ```
  模型回复预览：
  ```
  {
      "id": "chatcmpl-4e59963b1117f7fc23836254ef6cf238",
      "object": "chat.completion",
      "created": 1765193821,
      "model": "qwen2.5-vl-72b",
      "choices": [
          {
              "index": 0,
              "message": {
                  "role": "assistant",
                  "reasoning_content": null,
                  "content": "这张图片是一只可爱的柯基犬，它正坐在地上，舌头伸出来，看起来非常开心和友好。背景是户外的地面和一些绿色植物。",
                  "tool_calls": []
              },
              "logprobs": null,
              "finish_reason": "stop",
              "stop_reason": null
          }
      ],
      "usage": {
          "prompt_tokens": 283,
          "total_tokens": 911,
          "completion_tokens": 628,
          "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
  }
  ```
- [Java]
  建议JDK版本为15+。
  ```
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.time.Duration;
  import java.util.Base64;
  public class ImageDescriptionExample {
      public static void main(String[] args) throws Exception {
          // 接口地址
          String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
          String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key               
          String image_path = "test.png"; // test.png替换为真实的图片地址
          // 读取图片并转为 Base64
          String base64Image = encodeImageToBase64(image_path);
          String imageDataUrl = "data:image/png;base64," + base64Image;
          // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
          String modelName = "qwen2.5-vl-72b";
          // 构造请求体
          String requestBody = String.format(
                  """
                      {
                          "model": "%s",
                          "messages": [
                              {"role": "user",
                              "content": [
                               {"type": "text", "text": "描述下图片里的内容"},
                              {
                                  "type": "image_url",
                                  "image_url": {
                                      "url": "%s"
                                  }
                              }
                              ]}
                          ]
                      }""", modelName, imageDataUrl);
          // 创建 HttpClient
          HttpClient client = HttpClient.newBuilder()
                  .connectTimeout(Duration.ofSeconds(10))
                  .build();
          // 创建请求
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create(apiUrl))
                  .header("Content-Type", "application/json")
                  .header("Authorization", "Bearer " + apiKey)
                  .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                  .build();
          try {
              // 发送请求并打印结果
              HttpResponse<String> response = client.send(
                      request, HttpResponse.BodyHandlers.ofString());
              System.out.println("HTTP Status: " + response.statusCode());
              System.out.println("Response Body:\n" + response.body());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
      /**
       * 将图片文件转换为 Base64 编码字符串
       */
      private static String encodeImageToBase64(String imagePath) throws IOException {
          byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
          return Base64.getEncoder().encodeToString(imageBytes);
      }
  }
  ```
- [OpenAI SDK]
  ```
  import base64
  from openai import OpenAI
  base_url = "https://api.modelarts-maas.com/v1" # API地址
  api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key
  #  图片转Base64编码格式
  def encode_image(image_path):
      with open(image_path, "rb") as image_file:
          return base64.b64encode(image_file.read()).decode("utf-8")
  base64_image = encode_image("test.png")
  client = OpenAI(api_key=api_key, base_url=base_url)
  response = client.chat.completions.create(
      model = "qwen2.5-vl-72b", # model参数
      messages = [
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "描述下图片里的内容"},
                  {
                      "type": "image_url",
                      # 需要注意，Base64编码的图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
                      # Base64编码的PNG图像：  f"data:image/png;base64,{base64_image}"
                      # Base64编码的JPEG图像： f"data:image/jpeg;base64,{base64_image}"
                      # Base64编码的WEBP图像： f"data:image/webp;base64,{base64_image}"
                      # 公网图像地址： "https://example/xxx.png"
                      "image_url": {
                          "url": f"data:image/png;base64,{base64_image}"
                      }
                  }
              ]
          }
      ]
  )
  print(response.choices[0].message.content)
  ```
  模型回复预览：
  ```
  {
      "id": "chatcmpl-4e59963b1117f7fc23836254ef6cf238",
      "object": "chat.completion",
      "created": 1765193821,
      "model": "qwen2.5-vl-72b",
      "choices": [
          {
              "index": 0,
              "message": {
                  "role": "assistant",
                  "reasoning_content": null,
                  "content": "这张图片是一只可爱的柯基犬，它正坐在地上，舌头伸出来，看起来非常开心和友好。背景是户外的地面和一些绿色植物。",
                  "tool_calls": []
              },
              "logprobs": null,
              "finish_reason": "stop",
              "stop_reason": null
          }
      ],
      "usage": {
          "prompt_tokens": 283,
          "total_tokens": 911,
          "completion_tokens": 628,
          "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
  }
  ```
#### 多图输入场景示例
API可以同时接收并处理多个图像输入，可以通过将这些图像内容转换为Base64编码后输入，模型将结合所有传入的图像和提示词信息来回答问题。
传入Base64编码格式图片时，格式遵循data:image/\<图片格式\>;base64,\<Base64编码\> ，其中：
- 图片格式：jpeg、png、gif等，支持的图片格式详细见[图片格式说明]。
- Base64编码：图片的Base64编码。
以下为多图输入的图像理解示例代码，可通过model参数替换模型，model参数详情请参见[图像理解]。
- [OpenAI SDK]
  ```
  import base64
  import httpx
  from openai import OpenAI
  base_url = "https://api.modelarts-maas.com/v1" # API地址
  api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key
  client = OpenAI(api_key=api_key, base_url=base_url, http_client=httpx.Client(verify=False))
  response = client.chat.completions.create(
      model = "qwen2.5-vl-72b", # model参数
      messages = [
          {
              "role": "user",
              "content": [{
                  "type": "image_url",
                  "image_url": {
                      "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."
                  }
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "data:image/png;base64,WmMnpZKr54yMyLu+pZKrIz...."
                  }
               },
              {
                   "type": "text",
                   "text": "描述下图片里的内容"
               }]
           }
       ]
  )
  print(response.choices[0].message.content)
  ```
- [Curl]
  ```
  curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{ 
      "model": "qwen2.5-vl-72b",
      "messages": [
        {
          "role": "user",
          "content": [
              {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAA...."}},
       {"type": "image_url", "image_url": {"url": "data:image/png;base64,WmMnpZKr54yMyLu+pZKrIz...."}},
              {"type": "text", "text": "描述下图片里的内容"}
          ]
        }
      ]
    }'
  ```
- [Java]
  建议JDK版本为15+。
  ```
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.time.Duration;
  import java.util.Base64;
  /**
   * 多图理解
   */
  public class ImageDescriptionExample {
      public static void main(String[] args) throws Exception {
          // 接口地址
          String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
          String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key
          String image_path1 = "test1.png"; // test1.png替换为真实的图片地址
          String image_path2 = "test2.png"; // test2.png替换为真实的图片地址
          // 读取图片并转为 Base64
          String base64Image1 = encodeImageToBase64(image_path1);
          String base64Image2 = encodeImageToBase64(image_path2);
          String imageDataUrl1 = "data:image/png;base64," + base64Image1;
          String imageDataUrl2 = "data:image/png;base64," + base64Image2;
          // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
          String modelName = "qwen2.5-vl-72b";
          // 构造请求体
          String requestBody = String.format(
                  """
                      {
                          "model": "%s",
                          "messages": [
                              {"role": "user",
                              "content": [
                               {"type": "text", "text": "描述下图片里的内容"},
                              {
                                  "type": "image_url",
                                  "image_url": {
                                      "url": "%s"
                                  }
                              },
                              {
                                  "type": "image_url",
                                  "image_url": {
                                      "url": "%s"
                                  }
                              }
                              ]}
                          ]
                      }""", modelName, imageDataUrl1, imageDataUrl2);
          // 创建 HttpClient
          HttpClient client = HttpClient.newBuilder()
                  .connectTimeout(Duration.ofSeconds(10))
                  .build();
          // 创建请求
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create(apiUrl))
                  .header("Content-Type", "application/json")
                  .header("Authorization", "Bearer " + apiKey)
                  .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                  .build();
          try {
              // 发送请求并打印结果
              HttpResponse<String> response = client.send(
                      request, HttpResponse.BodyHandlers.ofString());
              System.out.println("HTTP Status: " + response.statusCode());
              System.out.println("Response Body:\n" + response.body());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
      /**
       * 将图片文件转换为 Base64 编码字符串
       */
      private static String encodeImageToBase64(String imagePath) throws IOException {
          byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
          return Base64.getEncoder().encodeToString(imageBytes);
      }
  }
  ```
#### 图文混排场景示例
API支持灵活交错地对提示词和图片信息进行序列编排，可以任意调整图片和文本的顺序，以及在system message或者User message传入图文信息。模型会根据顺序返回处理信息的结果，示例如下。可通过model参数替换模型，model参数详情请参见[图像理解]。
![](https://support.huaweicloud.com/model-call-maas/public_sys-resources/note_3.0-zh-cn.png)
图文混排场景，图片与文本顺序会影响模型输出效果，如果输入结果与预期不符，可以尝试更换图文和文本的顺序。
提示词支持图片和文字混排输入给模型，但图文顺序可能对模型的输出效果产生影响，特别是在图片较多且只有一段文字的情况下，建议拼接时将文字放在图片之后。
- [OpenAI SDK]
  ```
  import base64
  import httpx
  from openai import OpenAI
  base_url = "https://api.modelarts-maas.com/v1" # API地址
  api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key
  client = OpenAI(api_key=api_key, base_url=base_url, http_client=httpx.Client(verify=False))
  response = client.chat.completions.create(
      model = "qwen2.5-vl-72b", # model参数
      messages = [
          {
              "role": "user",
              "content": [
                   {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAA...."}},
                   {"type": "text", "text": "文字提取"},
                   {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."}},
            {"type": "text", "text": "描述下图片里的内容"}
               ]
           }
       ]
  )
  print(response.choices[0].message.content)
  ```
  
- [Curl]
  ```
  curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MAAS_API_KEY" \
    -d '{ 
      "model": "qwen2.5-vl-72b",
      "messages": [
        {
          "role": "user",
          "content": [
               {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAA...."}},
               {"type": "text", "text": "文字提取"},
               {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."}},
        {"type": "text", "text": "描述下图片里的内容"}
          ]
        }
      ]
    }'
  ```
- [Java]
  建议JDK版本为15+。
  ```
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.time.Duration;
  import java.util.Base64;
  public class ImageDescriptionExample {
      public static void main(String[] args) throws Exception {
          // 接口地址
          String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
          String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key
          String image_path1 = "test1.png"; // test1.png替换为真实的图片地址
          String image_path2 = "test2.png"; // test1.png替换为真实的图片地址
          // 读取图片并转为 Base64
          String base64Image1 = encodeImageToBase64(image_path1);
          String base64Image2 = encodeImageToBase64(image_path2);
          String imageDataUrl1 = "data:image/png;base64," + base64Image1;
          String imageDataUrl2 = "data:image/png;base64," + base64Image2;
          // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
          String modelName = "qwen2.5-vl-72b";
          // 构造请求体
          String requestBody = String.format(
                  """
                      {
                          "model": "%s",
                          "messages": [
                              {"role": "user",
                              "content": [
                               {"type": "text", "text": "描述下图片里的内容"},
                              {
                                  "type": "image_url",
                                  "image_url": {
                                      "url": "%s"
                                  }
                              },
                              {"type": "text", "text": "文字提取"},
                              {
                                  "type": "image_url",
                                  "image_url": {
                                      "url": "%s"
                                  }
                              }
                              ]}
                          ]
                      }""", modelName, imageDataUrl1, imageDataUrl2);
          // 创建 HttpClient
          HttpClient client = HttpClient.newBuilder()
                  .connectTimeout(Duration.ofSeconds(10))
                  .build();
          // 创建请求
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create(apiUrl))
                  .header("Content-Type", "application/json")
                  .header("Authorization", "Bearer " + apiKey)
                  .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                  .build();
          try {
              // 发送请求并打印结果
              HttpResponse<String> response = client.send(
                      request, HttpResponse.BodyHandlers.ofString());
              System.out.println("HTTP Status: " + response.statusCode());
              System.out.println("Response Body:\n" + response.body());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
      /**
       * 将图片文件转换为 Base64 编码字符串
       */
      private static String encodeImageToBase64(String imagePath) throws IOException {
          byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
          return Base64.getEncoder().encodeToString(imageBytes);
      }
  }
  ```