文档首页/ 智果（AgentArts）智能体平台/ 最佳实践/ API调用实践/ 使用API调用图像理解工作流
更新时间：2026-07-17 GMT+08:00
查看PDF
分享

使用API调用图像理解工作流

本案例中搭建一个图像理解工作流，实现通过多模态模型进行图像识别，并通过标准的RESTful API进行调用。

工作流部署时采用API Key认证，API调用也采用该方法。图像理解工作流的搭建、参数配置和文本类工作流存在差异，详见步骤一：搭建图像理解工作流。

使用API调用图像理解工作流时，图片约束如下：

  • 上传格式：.png、.jpg、.jpeg、.bmp、.gif，需使用图片的url地址，除支持公网图片地址外，支持使用华为云OBS服务的图片地址。图片地址需要公网可访问。
  • 上传大小：≤5 MB
  • 用户上传总量：200 MB/24h，同一用户24小时内累计不超过200MB
  • 用户上传次数：20次/5min，同一用户5分钟内最多上传20次

步骤一：搭建图像理解工作流

  1. 登录AgentArts智能体平台。
  2. 在左侧导航栏中选择“开发中心 > 智能体管理”，并进入“工作流”页签。
  3. 单击“创建工作流”，选择“任务型工作流”，填写名称、描述后，单击“立即创建”。

    创建完成后，平台会创建一个由“开始节点 - 大模型节点 - 结束节点”构成的工作流。
    图1 创建任务型工作流

  4. 单击“开始节点”。添加一个image参数，参数类型选择“Array<File> Image”，描述填写“图片”。

    图2 配置开始节点

  5. 单击“大模型节点”，选择一个图像理解模型（如Qwen2.5-VL-72B）。模型选择完成后，配置页面会新增一个“视觉理解输入”参数，选择开始节点中新增的image参数。

    大模型节点的其他参数保持默认。
    图3 选择图像理解模型
    图4 配置视觉理解输入

  6. 结束节点保持默认，工作流搭建完成后，单击“试运行”，输入准备好的图片和问题进行测试。

    图5 工作流试运行
    图6 查看运行结果

步骤二：部署工作流

本示例中的工作流部署时采用API Key认证，API调用也采用该方法。

  1. 工作流试运行无问题后，单击“提交版本”，需要勾选“部署至实例”选项。勾选后单击“确定”。

    图7 提交版本

  2. 入站身份认证选择“API Key”，并勾选日志记录、指标、调用链。其余配置可以使用默认值。

    图8 选择入站身份认证

  3. 单击“确定”部署工作流。

步骤三：获取API调用凭证（获取Authorization）

  1. 在左侧导航栏中选择“开发中心 > 智能体管理”选择需要调用的工作流，并复制ID。

    被调用的工作流需要是“已提交”状态。如果显示“未提交”，请单击工作流的名称，进入编辑页面，进行“提交版本”及部署操作。未部署状态的工作流无法获取调用凭证。

    图9 获取ID

  2. 获取ID后，在“部署运行 > 智能体运行时”页面搜索ID。

    图10 搜索ID

  3. 单击ID名称，进入基本信息页面，找到“访问与权限控制”对应的URN。单击URN名称。

    图11 单击URN名称

  4. 在页面中获取API Key的取值。

    获取API Key的值后，在API Key值前加上“Bearer ”即为Authorization的值（注意Bearer后有一个空格）。

    图12 获取API Key取值

步骤四：调用图像理解工作流

API接口：

POST /runtimes/{runtime_name}/invocations

API接口获取方法：

  1. 在左侧导航栏中选择“开发中心 > 智能体管理”，在“工作流”页签选择所需的工作流应用。
  2. 复制调用路径。（注意智能体需要经过发布，显示为“已提交”状态）

    图13 获取API接口

图片约束：

  • 上传格式：.png、.jpg、.jpeg、.bmp、.gif，需使用图片的url地址，除支持公网图片地址外，支持使用华为云OBS服务的图片地址。图片地址需要公网可访问。
  • 上传大小：≤5 MB
  • 用户上传总量：200 MB/24h，同一用户24小时内累计不超过200MB
  • 用户上传次数：20次/5min，同一用户5分钟内最多上传20次

核心请求参数说明：

表1 请求Header参数

参数

是否必选

参数类型

描述

Authorization

是

String

参数解释：

鉴权参数。获取方式请参考步骤三：获取API调用凭证（获取Authorization）。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

X-Invoke-Mode

否

String

参数解释：

该参数用于标识运行时运行的模式。

约束限制：

不涉及。

取值范围：

  • X-Invoke-Mode的值为debug时，运行模式为调试模式。调试模式会生成日志、详细的执行步骤，便于排查问题。

  • X-Invoke-Mode的值为published时，运行模式为发布模式。

默认取值：

published。

x-hw-agentarts-session-id

是

String

参数解释：

会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如“123e4567e89b12d3a456426614174000”，由用户自定义，无需在其他地方获取。

约束限制：

不涉及。

取值范围：

由英文、数字、“-”、“_”组成，不超过64位字符。

默认取值：

不涉及。

X-Request-Id

否

String

参数解释：

调用链ID，每个请求的唯一标识符。用于日志中跟踪整个请求的调用链路。用户可将调用链ID设置为任意字符串，例如“123e4567e89b12d3a4564266141740”，无需在其他地方获取。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

Content-Type

是

String

参数解释：

发送的实体的MIME类型。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

application/json。
表2 请求Body参数

参数

是否必选

参数类型

描述

inputs

是

Map<String,Object>

参数解释：

在调用工作流接口时，inputs对象中的字段（Key）并非API预留的固定字段，而是取决于您在工作流“开始节点”中定义的变量名。

图片传参示例：

{
    "inputs": {
        "query": "这个图片里面是什么",
        "image": [
            "https://support.huaweicloud.com/api-ocr/zh-cn_image_0000001746560801.png"
        ]
    }
}

约束限制：

为确保工作流正常运行，请遵循以下原则判断哪些变量需要传入：

  • 配置必填项：如果在“开始节点”中将某个变量设为“必填”，则调用API时必须包含该字段，且取值不能为空（如果后续节点未引用，可填写任意占位值）。
  • 逻辑引用项：如果某个变量在“开始节点”中设为“可选”，但其后的任何一个节点（如大模型节点、工具节点）引用了该变量，则调用API时必须传入该字段，否则会导致引用该变量的节点执行失败。
  • 可选忽略项：只有在“开始节点”中设为“可选”，且后续所有节点均未引用的情况下，该字段才可以在调用时省略。

取值范围：

不涉及。

默认取值：

不涉及。

Python调用示例：

import requests
import json

# 替换为真实的API接口
url = "https://{endpoint}/runtimes/{runtime_name}/invocations"

# 构造请求体：inputs 内部的 key 需对应工作流开始节点的变量定义
payload = json.dumps({
    "inputs": {
        "query": "这个图片里面是什么",
        "image": [
            "https://your-image-url.png"
        ]
    }
})

headers = {
    'Content-Type': 'application/json',
    'Authorization': '您的Authorization',
    'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符。'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

cURL调用示例：

针对不同操作系统，命令的转义和换行符有所不同。

  • Windows

    在CMD（命令提示符）中执行如下命令：

    curl -X POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: 您的Authorization" ^
  -H "x-hw-agentarts-session-id: 您的会话ID" ^
  -d "{ \"inputs\": { \"query\": \"这个图片里面是什么\", \"image\": [\"https://your-image-url.png\"] } }"
  • Linux/macOS

    在Terminal（终端）中执行如下命令：

    curl -X POST "https://{endpoint}/runtimes/{runtime_name}/invocations" \
  -H "Content-Type: application/json" \
  -H "Authorization: 您的Authorization" \
  -H "x-hw-agentarts-session-id: 您的会话ID" \
  -d '{
    "inputs": {
      "query": "这个图片里面是什么",
      "image": [
        "https://your-image-url.png"
      ]
    }
  }'
父主题： API调用实践

相关文档