# 更新图片理解模型

`POST` `/api/agent/updateImageModel`

设置智能体在 file 工具 view 图片（含 PDF、知识库文档内嵌图片）时使用的视觉模型，运行时优先于系统默认视觉模型。imageModelName 传 null 或空字符串表示清除自定义设置、恢复为系统默认视觉模型。模型按当前租户可用模型列表校验，且必须支持图片输入（「查询可用模型列表」接口返回的 inputModalities 包含 IMAGE），纯文本模型会被拒绝。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 是 | 智能体ID，必填 |
| imageModelName | string | 否 | 图片理解模型名称，对应智能体实体的 imageModelName 字段。传 null 或空字符串表示清除自定义设置，恢复为系统默认视觉模型。必须为「查询可用模型列表」接口返回且 inputModalities 包含 IMAGE 的模型（不区分大小写，由上游服务统一转小写存储） |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |