图片理解

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

MCP

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

{
  "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 credits计费，因此 8 张图片为 40 credits。 供应商 token 用量不改变本接口的客户扣费；失败任务不收费。

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