Skip to main content

​
概述

hellojint/updream-openai-compatible-plugin（GitHub） 是一款面向 Updream 桌面端 v0.2.0 的开源图片生成插件，以 通用 OpenAI 兼容图片 协议工作。安装后可以把桌面端的图片生成请求转发到满足 OpenAI Images 接口规范的第三方 API 上游，APIYI 在 API 路径上即满足此条件。
项目信息
  • 开源地址：github.com/hellojint/updream-openai-compatible-plugin
  • 许可证：MIT
  • 作者：hellojint
  • 插件包名：updream-openai-compatible-v1.updplugin
  • 基于：Updream 官方插件开发指南里的 OpenAI image-provider 示例
两种接入方式如果你不需要”本地执行任务 / 本地持有凭据”这类场景，优先使用 Updream 网页端： Updream 接入 API易（网页端）。网页端通过 “外部模型直连器” Skill + OpenAI 兼容 协议接入 APIYI，无需安装任何插件，是大多数用户的推荐路径。本文档介绍的桌面端 + 插件路径适合需要在本地持有 API Key、批量执行图片生成任务、或在 Web 端遇到 OpenAI Images 协议限制时的场景。

​
核心功能

通用 OpenAI 兼容协议

适用任何暴露 /v1/images/generations、鉴权使用 Bearer 的上游，APIYI 满足此条件

桌面端本地执行

任务在 Updream 桌面端 v0.2.0 本地执行，结果回到 Web 端画布

API-Key 本地保存

Key 由 Updream 在系统密钥链保存，运行时读取；插件本身不含任何凭据

多 Provider 共存

桌面端可同时配置多个 Provider（如 openai、apiyi-兼容），按需切换

尺寸自动映射

桌面端清晰度 + 比例自动映射成上游 size 参数；也支持 extra.size 硬写覆盖

多种返回格式

兼容 data[].url / data[].b64_json / 顶层 url 等多种返回结构，MIME 自动嗅探

​
支持的 APIYI 模型示例

下表给出在 Endpoint ID 字段可填的常见图像模型 ID，仅作示例：
实际可用模型请以 APIYI 模型推荐 为准，本表仅展示插件能写入的字段格式。

​
插件配置参数

插件加载到桌面端后，在「添加 API-Key」表单里有以下字段：
API Key 属于敏感凭证。不要把真实密钥写进任何截图、文档、Issue、README、聊天中。建议在 APIYI 控制台 为桌面端专门创建带用量上限的 Key，任务完成后及时撤销或删除。

​
安装与配置（按图步骤）

​
第 0 步：桌面端整体认识

Updream 桌面端任务总览（v0.2.0） 桌面端 v0.2.0 默认布局：左侧「本地执行」任务列表、顶部「同步 / 添加 Key / 导入插件 / 插件管理」、右下角版本号 v0.2.0。

​
第一步：导入插件

桌面端顶部「导入插件」入口 点击顶部「导入插件」按钮。在弹出的文件选择对话框中，选中下载好的 updream-openai-compatible-v1.updplugin，按提示确认安装。插件作者建议先审核 plugin.py 后再确认安装。

​
第二步：确认插件安装成功

插件安装后状态 在「插件管理」页可以看到已安装的 通用 OpenAI 兼容图片（universal-openai-compatible-image · v1.0.0 · image）。此时已具备桌面端调用任意 OpenAI Images 兼容上游的能力。

​
第三步：添加 Key

桌面端「添加 Key」入口 点击顶部「添加 Key」按钮，进入配置表单。

​
第四步：配置 APIYI

APIYI 配置示例 按图中示例填入： 填写后点击「测试连接」「测试生成」验证显示 连接成功！API 可用，再保存。

​
第五步：确认 Provider 已启用

Provider 列表 「配置」页的 Provider 列表里会出现新加的 apiyi-兼容，供应商标识为 plugin:universal-openai-compatible-image，状态 启用。可在多条 Provider 之间按需切换 / 禁用。
桌面端配置完成后，请重新进入 Updream Web 端，在画布节点的图片生成 Provider 下拉里选择 apiyi-兼容，即可从 Web 端发起任务、由桌面端执行。

​
使用：Web → 桌面端 → Web 闭环

完成上面 5 步之后，从 Updream Web 端发起一次图片生成，桌面端会按 apiyi-兼容 这个 Provider 的配置，把请求转发到 https://api.apiyi.com/v1/images/generations，结果回到 Web 端画布节点。 Web 端接收来自桌面端的生成结果 图中画布下方面板：图片生成 + apiyi-兼容（箭头位置）+ 16:9 / 2K / ×1 等输出参数。这是一张从 Updream Web 端发起、由桌面端执行、最终回到 Web 端画布的可视结果。

​
常见问题

请确认桌面端版本 ≥ v0.2.0。早期版本可能没有插件加载能力，需要先升级 Updream 桌面端。
  1. 确认 .updplugin 包根目录直接包含 plugin.py，与 manifest.entry 一致
  2. 重启桌面端
  3. 在「插件管理」页确认插件状态不是「已禁用」
  1. 检查 Endpoint ID 是否拼写正确，且在 APIYI 当前模型列表里
  2. 检查账户余额是否充足（参考 为什么还有余额跑不通）
  3. 在桌面端「本地执行」页查看具体错误码
Web 端不走本插件。请使用 Web 端的「外部模型直连器」Skill + OpenAI 兼容协议配置，或参考 Updream 接入 API易（网页端）。
修改 manifest.json.version 后重新打包：
注意 ZIP 根目录必须直接包含 plugin.py。
不会。本插件 不含任何凭据，Key 由 Updream 在系统密钥链保存，运行时通过 cfg.get('api_key') 读取；不要把真实 Key 写进 plugin.py、README、Issue 或聊天中。

​
相关资源

Updream 接入 API易（网页端，推荐）

网页端通过「外部模型直连器」Skill 接入 APIYI，无需安装插件

hellojint/updream-openai-compatible-plugin

本文档对应插件的开源仓库（MIT 许可）：github.com/hellojint/updream-openai-compatible-plugin

APIYI 模型推荐

查看 APIYI 当前支持的图像模型与定价

APIYI API 密钥管理

获取和管理 API Key 的最佳实践

APIYI 控制台

创建专用 Key、查看用量、设置余额上限

APIYI 接入与调用说明

查看 API 接入与 OpenAI 兼容协议说明