Home Assistantai_task.generate_image动作完全指南：用 AI 在自动化与脚本中生成图像
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
导读
ai_task.generate_image是 Home Assistant AI Task 集成提供的一个动作，用于"根据一段指令用 AI 生成一张图片"，并把结果以响应数据（response data）的形式返回给自动化或脚本继续使用。生成的图片会自动保存到 Home Assistant 的首个媒体目录中，可通过 Media source 集成在媒体浏览器里浏览。读完本文，你将掌握该动作在 UI 与 YAML 两种场景下的完整配置方法、全部参数的语义与默认行为、响应数据结构，以及如何用模板实体把 AI 图片"变成"一个可实时刷新的图像实体。
动作定位：AI Task 集成与生成式动作
ai_task.generate_image隶属于 AI Task 集成（ha_domain: ai_task，随 Home Assistant 2025.7 发布，质量等级为 internal）。AI Task 让你用 AI 帮助配置 Home Assistant，其公开动作只有两个：
ai_task.generate_image：根据指令生成图片（本文章主题）；- ai_task.generate_data：根据指令生成自由文本或结构化数据。
从动作变更记录看，ai_task.generate_image动作于 2025.9 版本被加入（见 core-2025.9 变更日志），随后在 2025.10 版本中 OpenAI 侧补齐了图像生成能力（见 core-2025.10 变更日志），2026.5 版本又新增了对gpt-image-2模型的支持（见 core-2026.5 变更日志）。这组记录表明：该动作的底层能力由所使用的 AI 对话集成（如 OpenAI）提供，因此并非所有 AI 对话实体都支持图像生成——文档明确要求所选实体"必须支持图像生成"。
与 generate_data 的区别
两者共享相同的调用框架（task_name、instructions、entity_id、attachments、response_variable），但generate_image聚焦于生成图像资源，其响应数据包含media_source_id、url、width、height等图像专有字段；而generate_data则侧重文本/结构化数据，且多一个structure参数。在集成主页的示例中，两者常被组合使用：一个生成天气图片，另一个生成文字描述。
行为特征：无目标（target）动作
ai_task.generate_image不支持 target 机制（即不能指定target:选择实体集合），这是它与大多数普通动作的关键差异。它的"作用对象"是任务本身：
- 通过
instructions描述要生成的图片； - 通过
entity_id（可选）指定运行在哪个 AI task 实体上； - 当省略
entity_id时，使用该 AI task 实体的首选（preferred）AI task 实体。
"首选实体"机制同样定义于 AI Task 集成文档：可以为每个 task 设置一个首选 AI task 实体，从而让不同的任务（生成文本、总结信息、控制设备）使用不同的 AI 模型。
动作执行后，生成的图片会保存到首个媒体目录中，可用 Media source 集成浏览。
在 UI 中使用该动作
以下步骤面向通过可视化编辑器构建自动化和脚本的用户：
- 进入Settings>Automations & scenes；
- 打开现有的自动化或脚本，或选择Create automation>Create new automation；
- 新建自动化时，在When区域添加触发器；脚本不需要触发器，它们在被其他东西调用时运行；
- 在Then do区域选择Add action；
- 在搜索框中搜索并选择AI Task: Generate image；
- 填写Task name与Instructions，并按需设置其他选项；
- 在Response variable字段中输入一个名称用于保存结果，例如
generated_image； - 选择Save。
UI 中的选项
| 选项 | 说明 | 必填 |
|---|---|---|
| Task name | 标识任务类型的名称，如 "floor map"（楼层地图）或 "weather visualization"（天气可视化） | 是 |
| Instructions | 解释要生成何种图片的具体指令 | 是 |
| Entity ID | 用于生成图片的 AI task 实体，该实体必须支持图像生成 | 是 |
| Attachments | 供 AI 作为参考使用的一组文件 | 否 |
其中Entity ID在 UI 中标记为必填，但从 YAML 语义看它本质上是可选的——YAML 模式下省略时会自动回退到首选实体，UI 只是显式地让你确认具体实体。
在 YAML 中使用该动作
在 YAML 中引用该动作的完整名称为ai_task.generate_image。文档给出的基础示例：
action: | action: ai_task.generate_image data: task_name: "weather visualization" instructions: "New York when the weather is sunny" response_variable: generated_image执行后，生成的图片结果会存入generated_image响应变量中，后续步骤可通过generated_image.url、generated_image.media_source_id等字段访问。
YAML 选项参考
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_name | string | 是 | 标识任务类型的名称，如 "floor map" 或 "weather visualization" |
instructions | string | 是 | 解释要生成何种图片的具体指令 |
entity_id | string | 否 | 要运行任务的 AI task 实体；未提供时使用首选 AI task 实体 |
attachments | list | 否 | 供 AI 作为参考的一组文件；每个附件都是 Media selector 的输出 |
attachments的具体用法可参考集成文档中的模板实体示例：以media_content_id: media-source://camera/camera.chicken_coop与media_content_type: image/jpeg的形式附加摄像头快照，实现多模态分析。
响应数据（Response data）
动作返回的响应数据是一个 mapping，包含以下字段：
| 字段 | 说明 |
|---|---|
media_source_id | 生成图片的 Media source 内容 ID |
url | 生成图片的 URL（不含主机部分）。该 URL 仅在一小时内有效 |
revised_prompt | 图像模型实际使用的提示词。部分模型会重写指令以补充细节或上下文 |
model | 用于生成图片的图像模型 |
mime_type | 图片的 MIME 类型 |
width | 图片宽度 |
height | 图片高度 |
conversation_id | 本次任务所使用的会话 ID |
两个值得注意的工程细节：
- URL 临时性：
url不带主机部分（使用时需自行拼接，如http://localhost:8123{{ url }}），且有效期只有一小时——若要在模板图片中持久展示，应优先使用media_source_id或配合模板实体的更新机制（见下文实例）； - 模型会改写提示词：
revised_prompt的存在说明底层图像模型可能对instructions进行扩充改写，审计生成内容时可借助该字段回溯"真实使用的提示词"。
图片的保存与浏览
- 生成的图片自动保存到首个媒体目录中，可用 Media source 集成在媒体浏览器中浏览；
- 文件命名格式为
{date}_{time}_{sanitized_task_name}.{ext}，例如2025-01-19_123456_home-security-camera.png——其中sanitized_task_name是任务名称经清理后的形式，这意味着task_name会影响最终文件名，命名时宜使用稳定的短标识。
Media source 集成还支持将网络存储映射为媒体目录（见 media_source 文档），配置后这些媒体也会自动出现在本地媒体浏览器中，便于统一浏览 AI 生成的图片。
实战组合：让"天气图片"自动刷新
AI Task 集成文档给出一个完整的端到端示例，展示了如何用ai_task.generate_image结合模板 image 实体实现"天气变化 → 重新生成图片 → 图片实体自动更新"：
automation: - alias: "Update image when weather changes" triggers: - trigger: state entity_id: weather.home actions: - alias: "Generate an image with AI Task" action: ai_task.generate_image response_variable: generated_image data: task_name: weather visualization instructions: >- New York when the weather is {{ states("weather.home") }} - alias: "Send out a manual event to update the image entity" event: new_weather_image event_data: url: '{{ generated_image.url }}' template: - trigger: - alias: "Update image when a new weather image is generated" trigger: event event_type: new_weather_image image: - name: "AI generated image of New York" url: "http://localhost:8123{{ trigger.event.data.url }}"这个例子清晰展现了该动作的三个关键集成点：
- instructions 支持模板：
{{ states("weather.home") }}将实时天气状态注入提示词，使图片内容随天气变化； - 响应变量跨步骤传递：
generated_image.url被写入自定义事件new_weather_image的event_data，实现动作 → 事件的解耦； - 模板 image 实体作为展示层：模板
image实体监听该事件并更新自身url，最终在仪表盘上呈现一张"跟随天气刷新"的 AI 图片（注意 URL 需拼上主机部分，与响应数据中url不含 host 的约定一致）。
用 Actions 工具快速试跑
如果只是想验证效果而不想先写 YAML，可以直接在Settings>Tools>Actions（开发者工具中的 Actions 页面）中搜索ai_task.generate_image，填写字段后点击Perform action，即可在实际实体上看到执行结果，无需编写任何 YAML。
常见问题与注意事项
- 实体必须支持图像生成：
entity_id指定的 AI task 实体需具备图像生成能力；若所选对话模型不支持，动作将无法成功。从变更日志看，OpenAI 的图像生成支持于 2025.10 版本落地，gpt-image-2于 2026.5 版本加入； - 不要依赖临时 URL 做长期展示：
url有效期仅一小时，长生命周期展示场景应通过media_source_id或模板实体事件机制实现刷新； task_name会影响文件名：文件以{date}_{time}_{sanitized_task_name}.{ext}命名，为不同用途的任务取稳定的名称（如 "weather visualization"、"home-security-camera"），便于在媒体浏览器中归档检索；- 与 generate_data 搭配使用：图片生成的同时，可用 ai_task.generate_data 生成配套的文字描述或结构化数据，例如"天气图片 + 幽默天气播报"的组合通知。
总结
ai_task.generate_image把"AI 文生图"能力封装成了 Home Assistant 原生动作：UI 模式适合快速上手，YAML 模式提供了task_name、instructions、entity_id、attachments四个核心参数的精确控制；配合响应数据中的media_source_id、url、revised_prompt等字段与模板 image 实体的事件驱动机制，可以构建出"天气一变图就换"这类完全自动化的动态图像工作流。理解"无 target 动作 + 首选实体回退 + 临时 URL"这三个行为约定，是正确使用该动作的关键。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
