# 图片理解
> 一次分析 1–8 张图片，采用稳定的输入限制与按张计价。

图片理解是同时通过认证 MCP 与 REST 提供的预览能力，能力和价格可能调整。提交 1–8 张有序
图片与提示词后，Beatra 返回可持久追踪的异步任务。

## MCP

调用 `beatra.images.understand`，并为一次逻辑请求生成稳定的
`client_request_id`：

```json
{
  "client_request_id": "understand-products-01",
  "model": "auto",
  "prompt": "比较这些商品并列出重要差异。",
  "images": [
    { "type": "url", "url": "https://example.com/front.jpg" },
    { "type": "artifact", "artifact_id": "artifact_back" }
  ],
  "detail": "default",
  "response_format": "text"
}
```

需要比较当前模型、限制或价格时，调用 `beatra.models.list` 并传入
`capability: "image_to_text"`。最终参数只提交一次，然后使用
`beatra.tasks.get` 和返回的 `task_id` 轮询到终态。成功后，答案同时位于
`structuredContent.task.output.text` 和 MCP 文本内容中。

对于本地图片，先用准确的 MIME 类型和字节数调用 `beatra.assets.upload`，按
返回信息执行 HTTPS `PUT` 上传原始字节，再把响应中的 `artifact_id` 作为
`artifact` 输入。上传后的源素材会保留在账号素材库。

## REST

将相同的理解字段（不含 `client_request_id`）提交到
`POST /v1/images/responses`，并发送稳定的 `Idempotency-Key` 请求头。使用
`GET /v1/tasks/{task_id}` 轮询到终态。

每张图片可使用你账户里的 `artifact`、外部 HTTPS `url` 或 base64
`data_uri`。外部和内联素材经过校验后会保存到账号的上传素材库，并通过
Beatra CDN 交给模型。

## 契约

- `prompt` 必填，且必须包含非空白文本。
- `images` 必填，支持 1–8 张有序图片。
- 每张图片解码后最大 10 MiB。
- `detail` 支持 `default`、`low`、`high`，默认为 `default`，不影响价格。
- 不暴露 `thinking`。MiniMax M3 内部固定启用 adaptive thinking。
- 可选模型为 `MiniMax-M3`；普通请求使用 `auto`，实时模型目录是可用性的
  最终依据。

## 计费

成功请求按**每张已接受的图片 5 积分**计费，因此 8 张图片为 40 积分。
供应商 token 用量不改变本接口的客户扣费；失败任务不收费。

输入素材会保留在账号素材库；接收素材时使用的服务器临时文件会在处理结束后删除。