Home Assistant 中 SwitchBot Cloud 上传 AI Art Frame 图片upload_art_frame_image动作实战指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本指南围绕 Home Assistant 的switchbot_cloud.upload_art_frame_image动作展开讲解如何把一张图片从网络地址推送到一个或多个 SwitchBot AI Art Frame 相框设备覆盖 UI 可视化配置、YAML 手写自动化/脚本示例、参数类型与必填项以及公网可达性、API 限额等关键约束。读完本文你将掌握用该动作实现定时轮换画作、家人回家显示照片、把 AI 生成图推上相框等自动化方案。动作概览它做了什么switchbot_cloud.upload_art_frame_image是 SwitchBot Cloud 集成 提供的动作自 2026.7 版本起可用。其作用非常简单直接你提供一个图片的网页地址SwitchBot 云服务代为下载该图片并下发到指定的一台或多台 AI Art Frame 相框上显示。从实现机制看图片的获取发生在 SwitchBot 云端而非 Home Assistant 本地这一点决定了它在地址可达性上的硬性要求详见下文“Good to know”部分。典型使用场景包括定时在相框上轮换展示不同的画作或照片墙当检测到有人回家时自动把欢迎照片或今日照片推送到相框在自动化中把刚生成的图片例如 AI 绘图产出的作品实时展示到相框上。在 UI 中配置该动作如果你习惯通过可视化界面搭建自动化或脚本无需手写 YAMLui_header 说明了这种使用方式Home Assistant 会引导你逐步完成配置。操作步骤如下进入SettingsAutomations scenes。打开一个已有的自动化或脚本如果是新建选择Create automationCreate new automation。新建自动化时在When部分添加触发条件脚本则不需要触发器脚本在被其他东西调用时才会执行。在Then do部分选择Add action。在搜索框中搜索并选择SwitchBot Cloud: Upload AI Art Frame image。在Devices下选择一个或多个 AI Art Frame 设备。在Image URL中填写要显示的图片的网页地址。选择Save保存。UI 中的选项选项说明Devices要在其上显示图片的一个或多个 AI Art Frame 设备。Image URL要上传的图片的网页地址。该地址必须能从互联网访问因为图片由 SwitchBot 云服务下载。在 YAML 中使用该动作如果你直接编写 YAML或者想精确知道 Home Assistant 底层做了什么可以参考本节的技术参考yaml_header。该部分列出了 YAML 中使用的字段名、类型和必填要求。在 YAML 中该动作以switchbot_cloud.upload_art_frame_image引用。单设备示例最基本的用法是向一台相框上传图片action: switchbot_cloud.upload_art_frame_image data: device_id: 1234567890abcdef1234567890abcdef image_url: https://example.com/artwork.png多设备示例要让同一张图片同时显示在多个相框上只需把device_id传为一个列表action: switchbot_cloud.upload_art_frame_image data: device_id: - 1234567890abcdef1234567890abcdef - fedcba0987654321fedcba0987654321 image_url: https://example.com/artwork.pngYAML 选项参数说明必填类型device_id要显示图片的 AI Art Frame 设备的 ID。要使用多个相框请传入设备 ID 列表。是string / listimage_url要上传的图片的网页地址。该地址必须能从互联网访问因为图片由 SwitchBot 云服务下载。是string关于这些参数在文档站点的呈现方式UI 选项由 options_ui.rb 渲染YAML 选项由 options_yaml.rb 渲染两者共用同一套config-vars样式与 Required/Optional 徽标example.rb 则负责把上面两个示例渲染为带语法高亮的代码块。完整自动化示例把上面的基本动作放入真实场景一个定时轮换画作的自动化大致如下alias: Rotate art on the AI Art Frame trigger: - platform: time at: 09:00:00 action: - action: switchbot_cloud.upload_art_frame_image data: device_id: 1234567890abcdef1234567890abcdef image_url: https://example.com/morning-art.png mode: single同样地你可以在“有人回家”自动化中用image_url指向家人照片的公开地址实现进门即展示的体验。Good to know两个关键约束原文档在 [Good to know] 一节强调了两个容易被忽略的事实图片必须公网可达SwitchBot 云服务自行抓取图片因此Home Assistant 本地的局域网地址在这里不适用。请使用互联网可访问的地址例如托管在公网图床、对象存储或你自己的公网 Web 服务器上的图片 URL。这也是本动作与本地文件上传类动作最大的区别——它绕过了本地网络完全依赖云端链路。计入 API 请求配额每次上传都会消耗一次 SwitchBot Cloud API 请求额度。关于配额细节请参见集成页面的 Important considerations集成页明确指出 SwitchBot Cloud API 将每个传感器限制为每 10 分钟600 秒请求一次状态更新且API 每日限额为 10,000 次请求。如果你的自动化高频触发图片上传需要把这一点纳入配额预算。从集成页的 AI Art Frame 设备能力清单见 switchbot_cloud.markdown 的 Image 小节可以看到AI Art Frame 支持获取电量、切换图片、显示当前图片以及通过本动作从网页地址上传新图片本动作是相框内容更新的核心入口。快速试运行想立即验证该动作而不写任何 YAML打开SettingsToolsActions搜索该动作填写字段后选择Perform action即可在真实实体上看到执行效果。这是排查 URL 可达性、设备 ID 是否正确的最快方式参见 try_it。排障提示如果动作执行后相框没有更新请按以下顺序检查URL 是否公网可达在普通浏览器或公网环境测试该地址能否直接打开局域网地址如192.168.x.x、http://homeassistant.local/...必然失败。设备 ID 是否正确device_id必须是 AI Art Frame 设备的 ID且支持列表形式批量下发ID 可在 SwitchBot 集成配置中确认。是否触发 API 限额查看集成页面的配额说明确认当日请求数没有达到上限。相框设备本身确认相框已通过 SwitchBot 云接入且在线。总结switchbot_cloud.upload_art_frame_image是一个结构极简、但云端链路特性突出的动作你只需要device_id和image_url两个必填参数即可把任意公网图片推送到一台或多台 AI Art Frame。掌握它的关键在于理解“图片由 SwitchBot 云下载”这一前提并合理规划 API 配额这样就能把它稳定地嵌入定时轮换、回家欢迎、AI 绘图展示等自动化流程中。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考