> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# AI 模型指南

> 先校验结构化文本输出再交给应用，并跟踪图片任务直到拿到可用的图片文件。

模型输出达到约定的可交付状态后，才交给下游。客服分类的可交付状态是：从 `choices[0].message.content` 解析出的字段通过 schema 校验。商品图的可交付状态是：`POST /v1/images/tasks` 创建的任务变为 `succeeded`，并且图片 URL 能打开。

## 把客服分类交给程序

按[文本接入](/zh/faq/model-sdk-setup)配置 SDK，并确认所选模型在所用协议上支持结构化输出。在 Chat Completions 请求里用 `response_format` 写明应用需要的结构。例如只收 `category`、`summary`，并把 `category` 限制在「安装、支付、其他」。

拿到回复后检查 `finish_reason`，解析 `choices[0].message.content`，再用同一份 schema 校验 `category` 和 `summary`。分类为「安装」且摘要是非空字符串的记录，进入安装队列。字段不齐、内容截断或拒答的记录，进入人工审核。

## 提交图片任务并跟踪一次

向 `POST https://api.beatapi.io/v1/images/tasks` 发 JSON，使用 BeatAPI Bearer 鉴权：

```json
{"model":"nano-banana","prompt":"A plain product photo of a reusable bottle on a light gray tabletop.","aspect_ratio":"1:1","output_format":"png"}
```

提交图片请求前，为这次请求生成一个专用的 `Idempotency-Key`。拿到响应里的 `data.id` 后，按 `data.poll_after_seconds` 的间隔查询 `GET /v1/tasks/{task_id}`。任务为 `succeeded` 时，从 `data.output.media` 取图片 URL，确认图片能打开，并在素材记录里保存任务 ID。提交时断线，按[图片幂等重试](/zh/faq/model-idempotent-retry)接回原任务。

[AI 模型常见问题](/zh/faq/models) · [BeatAPI 价格页](https://beatapi.io/zh/pricing)