Python 飞书推送图片常见技术问题：如何正确上传并推送图片到飞书群机器人？

Question

**问题描述：** 在使用 Python 向飞书群机器人推送图片时，常遇到图片上传失败、返回 `image_key` 无效或推送消息格式错误等问题。开发者需了解如何正确调用飞书机器人 API，包括获取 `image_key`、上传图片二进制数据、构造正确的消息体格式（如 `post` 或 `image` 类型），以及处理鉴权与速率限制等常见问题。

Answer 1

一、飞书群机器人推送图片常见问题与解决方案

在使用 Python 向飞书群机器人推送图片时，开发者常遇到图片上传失败、返回 image_key 无效或消息格式错误等问题。本文将从基础 API 调用到高级问题排查，逐步深入解析解决方案。

1. 基本流程概述

向飞书群机器人发送图片消息，主要分为以下几个步骤：

1. 获取 Webhook URL（包含机器人密钥）
2. 上传图片二进制数据，获取 image_key
3. 构造消息体，使用 image_key 推送图片消息

2. 获取 Webhook URL

在飞书开放平台创建群机器人后，会生成一个 Webhook URL，格式如下：

https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-token

该 URL 是推送消息的目标地址，需在请求头中设置 Content-Type: application/json。

3. 图片上传与获取 image_key

飞书 API 要求先将图片上传至服务器，获取 image_key 后方可发送消息。上传图片使用如下接口：

POST https://open.feishu.cn/open-apis/im/v1/images?access_token={token}

请求头需包含 Content-Type: multipart/form-data，请求体包含图片二进制数据。

4. 示例代码：上传图片并获取 image_key

import requests

webhook_url = "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-token"
image_path = "test.jpg"

# Step 1: 获取 access_token（需要先通过 app_id 和 app_secret 获取）
access_token = get_access_token()

# Step 2: 上传图片
with open(image_path, "rb") as f:
    files = {"image": f}
    upload_url = f"https://open.feishu.cn/open-apis/im/v1/images?access_token={access_token}"
    response = requests.post(upload_url, files=files)
    image_key = response.json()["data"]["image_key"]
    

5. 构造消息体并发送

使用 image_key 发送图片消息，支持 image 类型或嵌入在 post 类型中。示例 JSON 消息体如下：

{
    "msg_type": "image",
    "content": {
        "image_key": "img-vrCxxxxxx"
    }
}
    

发送请求：

requests.post(webhook_url, json=message_body)
    

6. 常见问题与排查

• 返回 image_key 无效：可能图片上传失败或未正确获取 image_key，需检查上传接口响应。
• 消息格式错误：确认 msg_type 和 content 结构是否符合文档要求。
• 鉴权失败：检查 access_token 是否有效，或是否遗漏签名验证。
• 速率限制：飞书 API 有调用频率限制，建议使用重试机制或队列控制。

7. 鉴权机制详解

飞书机器人支持两种鉴权方式：

方式	说明
Webhook Token	用于基础消息推送，包含在 Webhook URL 中
Sign 签名	需在请求体中添加 sign 字段，防止伪造请求

8. 完整流程图

graph TD
            A[准备图片] --> B[获取 access_token]
            B --> C[上传图片获取 image_key]
            C --> D[构造消息体]
            D --> E[发送消息至 Webhook URL]

9. 性能优化与稳定性建议

为提高系统稳定性，建议：

• 使用异步任务队列（如 Celery）处理图片上传与消息发送
• 实现重试机制，应对网络波动或 API 限流
• 记录日志并监控 API 调用成功率

10. 扩展应用场景

除了基础图片推送，飞书机器人还可用于：

• 图文混排消息（post 类型）
• 带按钮的交互式消息
• 结合定时任务自动推送日报、监控告警等