---
docStatus: current
---

# 统一内容协议（Content Parts）

使用有序 content 数组描述文字、图片、音频、视频和文件，区分内容、通知属性与渠道投递能力。

百积木使用 `content` 数组描述消息正文。数组中的每一项是一个内容片段，通过 `type` 标识类型。
本页说明 Content Parts **1.0.0**。这是一份平台内容协议；对接模型提供商或外部渠道时，由适配层转换为对方的格式。

## 基本结构

`content` 必须是非空数组，每项必须是对象。数组顺序就是内容顺序，即使只有一段文字也使用数组。
生产者使用下文规定的小写 `type`，并提供对应内容字段。1.0.0 的校验会拒绝未知类型和未知字段；
正文与资源字段按原值保留，空白检查不会修改正文。

```json
{
  "content": [
    { "type": "text", "text": "报告已生成，请查看附件。" },
    {
      "type": "file",
      "file": {
        "url": "https://example.com/report.pdf",
        "name": "报告.pdf",
        "mimeType": "application/pdf"
      }
    }
  ]
}
```

示例地址仅用于说明格式。实际资源必须能够被目标消费者按其授权方式访问；不要假定浏览器中可打开的
地址就一定能被外部渠道读取。

## 当前内容类型

| `type`  | 对应字段       | 必填要求                                 |
| ------- | ---------- | ------------------------------------ |
| `text`  | `text` 字符串 | 去除首尾空白后不能为空。                         |
| `image` | `image` 对象 | 包含非空字符串 `url`；可提供 `name`、`mimeType`。 |
| `audio` | `audio` 对象 | 包含非空字符串 `url`；可提供 `name`、`mimeType`。 |
| `video` | `video` 对象 | 包含非空字符串 `url`；可提供 `name`、`mimeType`。 |
| `file`  | `file` 对象  | 包含非空字符串 `url`；可提供 `name`、`mimeType`。 |

`name` 是资源展示名称，`mimeType` 是资源的媒体类型。它们不能替代资源地址。
地址协议、文件大小、格式和访问条件还受具体接口及渠道限制。

```json
{
  "content": [
    { "type": "text", "text": "以下是本次沟通的材料。" },
    { "type": "image", "image": { "url": "https://example.com/photo.png" } },
    {
      "type": "audio",
      "audio": { "url": "https://example.com/voice.mp3", "name": "录音.mp3", "mimeType": "audio/mpeg" }
    },
    {
      "type": "video",
      "video": { "url": "https://example.com/demo.mp4", "name": "演示.mp4", "mimeType": "video/mp4" }
    },
    {
      "type": "file",
      "file": { "url": "https://example.com/report.pdf", "name": "报告.pdf", "mimeType": "application/pdf" }
    }
  ]
}
```

这些是内容片段示例，不代表一个渠道支持将全部片段合并成一条原生消息。

## 内容与消息外层

内容协议只描述正文，不定义接收人、会话、通知类别或投递状态。

- 接收人、工作区与会话由具体调用接口定义。
- 通知的 `category`、`urgency` 属于整条通知的属性，位于 `content` 外层。
- 消息事件的类型与内容片段的 `type` 是两个不同概念。
- 工具调用、工具结果和业务执行状态不属于这里的内容类型。

链接放在文本中，例如 `{"type":"text","text":"查看报告：https://example.com/report"}`。
当前未定义独立的 `link`、`button`、`html`、`card` 或 `form` 类型。`text` 也不意味着所有消费者都会
执行 HTML 或以相同方式渲染 Markdown。

本页定义内容结构，不声明某个工作区已安装通知模块。调用前仍须发现实际服务并读取
`methodDefinition`；通知接口的可用性和投递状态见[通知与投递](/development/organization-capabilities/notifications/)。

## 扩展与渠道能力

新增内容类型时，外层仍使用 `content[]`。扩展必须统一定义类型名称、字段、校验、版本和消费者支持范围，
不能只传一个新 `type` 就假定所有接口都能处理。当前发送入口会拒绝五种已登记类型之外的内容类型。

区分两个检查：内容是否合法，以及目标渠道能否投递。通过内容校验并不保证外部渠道能够展示所有片段。
当前渠道适配可能将媒体转成可读文本或省略不支持的片段；对内容完整性有要求时，需要核对该渠道的实际能力
和投递结果，不能把受理成功当作完整展示的证明。

## 与 OpenAI 格式的关系

内容数组和类型字段是共同的设计方式，字段结构并不相同。例如图片片段：

| 协议                      | 图片片段                                           |
| ----------------------- | ---------------------------------------------- |
| 百积木                     | `{"type":"image","image":{"url":"…"}}`         |
| OpenAI Chat Completions | `{"type":"image_url","image_url":{"url":"…"}}` |
| OpenAI Responses        | `{"type":"input_image","image_url":"…"}`       |

调用模型时必须使用对应适配，不能把百积木正文直接当作 OpenAI 请求发送。
第三方字段以 [OpenAI Chat Completions 文档](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
和 [Responses 图片输入文档](https://developers.openai.com/api/docs/guides/images-vision)为准。