diff --git a/lark_document_upload_images.md b/lark_document_upload_images.md new file mode 100644 index 0000000..3e14a7e --- /dev/null +++ b/lark_document_upload_images.md @@ -0,0 +1,114 @@ +# 飞书文档原生插入图片/视频 — 干货速查 + +> `TOKEN` 所有 API 通用,`DOC_ID` 为文档 ID。下面全部 curl 可直接复制执行。 + +## 0. 前置:获取 Token & 创建文档 + +```bash +# 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_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) + +```bash +# 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,预览视图) + +```bash +# 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. 附加操作 + +```bash +# 插入文本/标题块 +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 不支持 | 用本文档原生流程 |