5.4 KiB
5.4 KiB
飞书文档原生插入图片/视频 — 干货速查
TOKEN所有 API 通用,DOC_ID为文档 ID。下面全部 curl 可直接复制执行。
0. 前置:获取 Token & 创建文档
# Token (2h 有效)
TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-H "Content-Type: application/json" \
-d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")
# 创建空白文档
DOC_ID=$(curl -s -X POST "https://open.feishu.cn/open-apis/docx/v1/documents" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"title":"文档标题"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['document']['document_id'])")
1. 插入图片(block_type=27)
# Step 1: 创建空占位块
BLOCK_ID=$(curl -s -X POST \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"children":[{"block_type":27,"image":{}}],"index":-1}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['children'][0]['block_id'])")
# Step 2: 上传原图
FILE_TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/medias/upload_all" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/path/to/image.png" -F "file_name=image.png" \
-F "parent_type=docx_image" -F "parent_node=${BLOCK_ID}" \
-F "size=$(stat -c%s /path/to/image.png)" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['file_token'])")
# Step 3: 回填 token(不执行此步图片不显示!)
curl -s -X PATCH \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${BLOCK_ID}?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"replace_image\":{\"token\":\"${FILE_TOKEN}\"}}" > /dev/null
2. 插入视频(block_type=23,预览视图)
# Step 1: 创建 File 占位块 (view_type=2=预览, view_type=1=文件卡片)
VIEW_ID=$(curl -s -X POST \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"children":[{"block_type":23,"file":{"view_type":2}}],"index":-1}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['children'][0]['block_id'])")
# 取出内部真正的 File block ID(非 View block ID!)
FILE_ID=$(curl -s \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${VIEW_ID}?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['block']['children'][0])")
# Step 2: 上传视频 (parent_node=FILE_ID,不是 VIEW_ID!)
FILE_TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/medias/upload_all" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/path/to/video.mp4" -F "file_name=video.mp4" \
-F "parent_type=docx_file" -F "parent_node=${FILE_ID}" \
-F "size=$(stat -c%s /path/to/video.mp4)" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['file_token'])")
# Step 3: 回填 token
curl -s -X PATCH \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${FILE_ID}?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"replace_file\":{\"token\":\"${FILE_TOKEN}\"}}" > /dev/null
3. 附加操作
# 插入文本/标题块
curl -s -X POST \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"children":[{"block_type":3,"heading1":{"elements":[{"text_run":{"content":"章节标题","text_element_style":{}}}],"style":{}}}],"index":-1}' > /dev/null
# block_type: 2=正文, 3=Heading1, 4=Heading2, ...
# 批量删除子块 (左闭右开 [start, end))
curl -s -X DELETE \
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children/batch_delete?document_revision_id=-1" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"start_index":0,"end_index":3}' > /dev/null
4. 图片 vs 视频 对照
| 图片 | 视频 | |
|---|---|---|
| block_type | 27 | 23 |
| 占位块 JSON | {"block_type":27,"image":{}} |
{"block_type":23,"file":{"view_type":2}} |
| 实际产物 | Image block | View(33) 包裹 File(23) 复合块 |
upload parent_type |
docx_image |
docx_file |
upload parent_node |
Image block ID | File block ID(非 View ID!) |
| PATCH 字段 | replace_image |
replace_file |
| PATCH 目标 | Image block | File block |
5. 坑
| 症状 | 根因 | 解法 |
|---|---|---|
| 图片/视频上传后不显示 | token 不回填 | 必须 PATCH replace_image/replace_file |
| 视频永久转圈 | parent_node 填了 View ID |
取 View.children[0] 得到 File ID |
| 创建 file 块报 1770001 | 预设了 name/token |
只传 {"view_type":2},name/token 后续回填 |
| 视频只有文件卡片无播放器 | 未设 view_type=2 | 创建时 "file":{"view_type":2},创建后无法修改 |
| 旧 import API 图片不渲染 | base64 data URI 不支持 | 用本文档原生流程 |