# 使用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次 #### 前置检查 - 已开通AgentArts服务。 - 已接入可用模型。调用智能体/工作流API时不支持使用平台赠送的免费token，确保配置的模型满足以下任一条件： - 接入华为云MaaS服务模型并配置模型API Key（平台默认模型来源），操作请参考[接入华为云MaaS服务付费模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0095.html)。 - 已在智能体/工作流中自行对接外部第三方模型，操作请参考[手动接入和使用OpenAI协议模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0096.html)。 未接入MaaS模型且未使用第三方模型时，调用API将返回"Model call failed"报错。 #### 步骤一：搭建图像理解工作流 1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏中选择"开发中心 \> 智能体管理"，并进入"工作流"页签。 3. 单击"创建工作流"，选择"任务型工作流"，填写名称、描述后，单击"立即创建"。 创建完成后，平台会创建一个由"开始节点 - 大模型节点 - 结束节点"构成的工作流。 图1创建任务型工作流 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661722497.png "点击放大") 4. 单击"开始节点"。添加一个image参数，参数类型选择"Array\ Image"，描述填写"图片"。 图2配置开始节点 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661603635.png "点击放大") 5. 单击"大模型节点"，**选择一个图像理解模型** （如Qwen2.5-VL-72B）。模型选择完成后，配置页面会新增一个"视觉理解输入"参数，选择开始节点中新增的image参数。 大模型节点的其他参数保持默认。 图3选择图像理解模型 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002631404638.png "点击放大") 图4配置视觉理解输入 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661724129.png "点击放大") 6. 结束节点保持默认，工作流搭建完成后，单击"试运行"，输入准备好的图片和问题进行测试。 图5工作流试运行 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002631405490.png "点击放大") 图6查看运行结果 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661605053.png "点击放大") #### 步骤二：部署工作流 **本示例中的工作流部署时采用API Key认证，API调用也采用该方法。** 1. 工作流试运行无问题后，单击"提交版本"，需要勾选"部署至实例"选项。勾选后单击"确定"。 图7提交版本 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002674600684.png "点击放大") 2. 入站身份认证选择"API Key"，并勾选日志记录、指标、调用链。其余配置可以使用默认值。 图8选择入站身份认证 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661606583.png "点击放大") 3. 单击"确定"部署工作流。 #### 步骤三：获取API调用凭证（获取Authorization） 1. 在左侧导航栏中选择"开发中心 \> 智能体管理"选择需要调用的工作流，并复制ID。 被调用的工作流需要是"已提交"状态。如果显示"未提交"，请单击工作流的名称，进入编辑页面，进行"提交版本"及部署操作。未部署状态的工作流无法获取调用凭证。 图9获取ID ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002631407856.png "点击放大") 2. 获取ID后，在"部署运行 \> 智能体运行时"页面搜索ID。 图10搜索ID ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002643083194.png "点击放大") 3. 单击ID名称，进入基本信息页面，找到"访问与权限控制"对应的URN。单击URN名称。 图11单击URN名称 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661607313.png "点击放大") 4. 在页面中获取API Key的取值。 获取API Key的值后，在API Key值前加上"Bearer "即为Authorization的值（注意Bearer后有一个空格）。 图12获取API Key取值 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002631408056.png "点击放大") #### 步骤四：调用图像理解工作流 **API接口：** POST /runtimes/{runtime_name}/invocations **API接口获取方法：** 1. 在左侧导航栏中选择"开发中心 \> 智能体管理"，在"工作流"页签选择所需的工作流应用。 2. 复制调用路径。（注意智能体需要经过发布，显示为"已提交"状态） 图13获取API接口 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661608033.png "点击放大") **图片约束：** - 上传格式：.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\ | **参数解释**： 在调用工作流接口时，inputs对象中的字段（Key）并非API预留的固定字段，而是取决于您在工作流"开始节点"中定义的变量名。 **图片传参示例：** ``` { "inputs": { "query": "这个图片里面是什么", "image": [ "https://support.huaweicloud.com/api-ocr/zh-cn_image_0000001746560801.png" ] } } ``` **约束限制**： 为确保工作流正常运行，请遵循以下原则判断哪些变量需要传入： - **配置必填项**：如果在"开始节点"中将某个变量设为"必填"，则调用API时必须包含该字段，且取值不能为空（如果后续节点未引用，可填写任意占位值）。 - **逻辑引用项**：如果某个变量在"开始节点"中设为"可选"，但其后的任何一个节点（如大模型节点、工具节点）引用了该变量，则调用API时必须传入该字段，否则会导致引用该变量的节点执行失败。 - **可选忽略项**：只有在"开始节点"中设为"可选"，且后续所有节点均未引用的情况下，该字段才可以在调用时省略。 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002661737197.png "点击放大") **取值范围**： 不涉及。 **默认取值**： 不涉及。 | **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，格式为Bearer {api_key}', '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，格式为Bearer {api_key}" ^ -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，格式为Bearer {api_key}" \ -H "x-hw-agentarts-session-id: 您的会话ID" \ -d '{ "inputs": { "query": "这个图片里面是什么", "image": [ "https://your-image-url.png" ] } }' ```