AINativeNotes/lark_document_upload_images.md

5.4 KiB
Raw Permalink Blame History

飞书文档原生插入图片/视频 — 干货速查

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 不支持 用本文档原生流程