请求头：
Content-Type: application/json
Authorization: Bearer accesstoken>

请求体：
{
children: [ ...块数组... ],
index: 0
}

• - blockid：父块 ID（根节点通常为 documentid 本身）
• index：插入位置（0 = 开头，-1 或省略 = 末尾）

块 JSON 示例

文本

json
{
block_type: 2,
text: {
elements: [{
text_run: {
content: 此处为段落文本,
textelementstyle: { bold: false, italic: false }
}
}]
}
}

标题

json
{ blocktype: 3, heading1: { elements: [{ textrun: { content: H1 标题 } }] } }
{ blocktype: 4, heading2: { elements: [{ textrun: { content: H2 标题 } }] } }

无序列表 / 有序列表

json
{ blocktype: 12, bullet: { elements: [{ textrun: { content: 列表项目 } }] } }
{ blocktype: 13, ordered: { elements: [{ textrun: { content: 编号项目 } }] } }

每个列表项是一个独立的块。

代码块

json
{
block_type: 14,
code: {
elements: [{ text_run: { content: console.log(hello); } }],
style: { language: 23, wrap: false }
}
}

常用语言枚举：纯文本=1, JavaScript=23, Python=40, TypeScript=49, Go=20, Shell=46, SQL=47, Java=22, Rust=44, C=12, CSS=17, HTML=21, Docker=19。

高亮块（飞书特有的高亮框）

高亮块是一个容器块——先创建它，然后在内部添加子块。

json
// 步骤1：创建高亮块作为文档子块
{ blocktype: 19, callout: { backgroundcolor: 3, bordercolor: 3, emojiid: star } }

// 步骤2：POST .../blocks/{calloutblockid}/children
{ children: [{ blocktype: 2, text: { elements: [{ textrun: { content: 高亮文本 } }] } }] }

颜色枚举：红色=1, 橙色=2, 黄色=3, 绿色=4, 蓝色=5, 紫色=6, 灰色=7。

分割线

json
{ block_type: 22, divider: {} }

图片（两步操作）

步骤1：创建占位块 { block_type: 27, image: {} }
步骤2：通过 POST /open-apis/drive/v1/medias/upload_all 上传
- multipart/form-data: file, filename, parenttype=docximage, parentnode=blockid>

文本样式

通过 textrun 中的 textelement_style 应用样式：

一个块中包含多个 text_run 元素 = 同一段落中的混合样式。

Markdown 到块的映射

并发与排序（关键）

问题：并发创建块的 API 调用会产生随机排序。

方案 A：单次批量请求（推荐）

将所有块放在一个 children 数组中，单次 API 调用：

json
{
children: [
{ blocktype: 3, heading1: { elements: [{textrun: {content: 标题}}] } },
{ blocktype: 2, text: { elements: [{textrun: {content: 段落1}}] } },
{ block_type: 22, divider: {} },
{ blocktype: 4, heading2: { elements: [{textrun: {content: 章节2}}] } }
],
index: 0
}

方案 B：带索引的串行写入

对于需要多次请求的长内容