WeryAI 图像生成器

使用官方基础技能，支持文本生成图像（text-to-image）与图像生成图像（image-to-image）工作流。在智能体（agent）环境中，默认采用“图像优先”流程：先提交任务，再轮询状态，直至最终图像就绪，或达到最长超时时间（5 分钟，即 300 秒）。禁止运行无界轮询循环。请将 taskId 或 batchId 视为追踪数据而非调用终点；仅当用户明确要求“先返回 ID”或任务在完成前已超时时，才将其作为主要输出呈现。wait-image.js 仅在用户明确要求“一次性提交并阻塞等待结果”时使用。

示例提示词

• 生成这张图像，并持续检查直到我能查看最终图像，或在 5 分钟超时后停止。
• 将此参考图像转为电影级海报，并仅在我主动询问状态时检查结果。
• 使用 WeryAI 图像生成图像功能重绘此图像，并在最终图像就绪时向我展示。
• 在生成前，先查询哪些 WeryAI 图像模型支持 9:16 纵向比例和输出 4 张图像。
• 查询我的 WeryAI 图像生成任务状态，并告诉我图像是否已就绪。

快速概览

• 核心任务类型：text-to-image、image-to-image、image from prompt、restyle this image、task status、最终图像交付
• 默认模型：WeryAI Image 2.0（WERYAI_IMAGE_2_0）
• 默认参数：image_number=1、aspect_ratio=9:16
• 关键可信信号：支持 dry-run 模式、模型能力查询、付费运行预警、媒体源校验（本地参考图自动上传）

身份认证与首次配置

首次执行真实图像生成前，请完成以下步骤：

1. 注册 WeryAI 账户。
2. 访问 API 密钥页面：https://www.weryai.com/api/keys。
3. 创建新的 API 密钥，并复制其密钥值（secret value）。
4. 将该密钥值写入必需的环境变量 WERYAI_API_KEY。
5. 确保 WeryAI 账户中已有可用余额或积分，以支持付费生成。

OpenClaw 友好型配置

• 本技能已在 metadata.openclaw.requires.env 和 primaryEnv 中声明 WERYAI_API_KEY。
• 安装完成后，若安装器或运行时提示需配置必需环境变量，请将密钥粘贴至 WERYAI_API_KEY 字段。
• 如需手动配置运行时，请在执行命令前导出该变量：

export WERYAI_API_KEY="your_api_key_here"

快速验证

在首次付费运行前，建议执行一次安全检查：

node scripts/models-image.js --mode text_to_image
node scripts/wait-image.js --json '{"prompt":"雾中一盏发光的纸灯笼","aspect_ratio":"9:16"}' --dry-run

• models-image.js 用于确认密钥已正确配置且模型接口可正常访问。
• --dry-run 可在本地预览请求结构，不消耗积分。
• 真实的 wait 或 submit-* 命令仍需账户具备可用 WeryAI 余额。

前提条件

• 执行付费运行前，必须设置 WERYAI_API_KEY。
• 需 Node.js >=18 版本，因运行时依赖内置 fetch API。
• 图像生成图像（image-to-image）任务中，参考图像可为 http/https URL 或本地文件路径；本地/非 http(s) 路径将通过 /v1/generation/upload-file 接口自动上传。
• 真实的 submit 与 wait 运行将消耗 WeryAI 积分。

安全与 API 主机

• 请严格保密 WERYAI_API_KEY，切勿将其写入代码仓库。
• 本技能支持直接传入本地文件路径；若提供本地路径，运行时将自动将该文件上传至 WeryAI 服务器进行处理。
• 可选覆盖项 WERYAI_BASE_URL 与 WERYAI_MODELS_BASE_URL 默认分别指向 https://api.weryai.com 与 https://api-growth-agent.weryai.com；仅可在确认主机可信的前提下进行覆盖。
• 如需更高安全保障，请在生产环境部署前审阅 scripts/ 目录下的全部脚本。

支持的意图类型

• 文本简述 → 从零生成一张或多张图像。
• 单张参考图像 → 对该图像进行重绘或转换。
• 已有任务 → 查询图像生成状态，而非新建付费任务。
• 参数或模型相关问题 → 先查询 models，再提交生成请求。

默认配置

除非用户显式更改，否则默认采用以下配置：

• model：WERYAI_IMAGE_2_0（WERYAI_IMAGE_2_0）
• image_number：1
• aspect_ratio：9:16

始终允许用户覆盖 model、image_number、aspect_ratio 和 resolution。当用户请求不被支持的设置时，应先运行 models-image.js，并仅保留所选模型实际支持的取值。

模型切换与参数引导策略

采用渐进式引导方式，而非一次性解释所有参数。

• 若用户仅需生成一张图像，直接采用默认配置：**WeryAI Image 2.0**（WERYAI_IMAGE_2_0）。
• 若用户提出更换模型、提升画质、增加图像数量、调整宽高比或指定分辨率等需求，则进入参数确认模式。
• 若用户已明确所需具体参数，可直接应用；仅在必要时校验模型是否支持该参数。
• 若用户表述模糊或不确定，应将其创意需求映射为最接近的支持参数，而非要求其自行选择原始 API 字段。

推荐引导模式

采用简洁的操作员风格引导语，例如：

• 通用帮助：当用户询问“如何使用本技能”时，切勿粘贴原始 shell 命令；而应使用自然语言说明能力范围，并提供 2–3 个典型提示词示例。
• 默认运行： 我可先按默认配置启动：WeryAI Image 2.0、1 张图像、9:16 宽高比。若您需要，我也可以在提交前切换模型，或调整图像数量、宽高比及分辨率。
• 模型切换： 若您希望更换模型，请告知您更关注 realism（写实性）、stylization（风格化）、reference-image fidelity（参考图保真度）、更高分辨率还是更多输出图像数量，我将优先查询当前支持的模型列表。
• 参数变更： 我可以将您的需求映射为图像设置。例如：“竖版封面”→9:16，“方形帖文”→1:1，“更多选项”→image_number 设为 4，“更清晰输出”→选用该模型支持的最高分辨率。
• 付费运行前的安全确认： 在我提交付费任务前，我会展示最终选定的模型、参数及提示词，供您确认。

何时发起追问

仅在提交任务所必需的最小缺失信息时发起追问。

• 当用户提及“海报”、“封面图”、“壁纸”、“方形帖文”或“竖向社交卡片”等平台场景时，询问 aspect_ratio。
• 当用户希望获得多个选项或变体时，询问 image_number。
• 仅当用户明确要求“更高画质”或目标模型支持多档分辨率时，才询问 resolution。
• 仅当用户明确要求更换模型，或模型能力支持尚不明确时，才询问模型选择。
• 若默认配置已完全满足用户请求，则无需对每个参数逐一提问。

用户语言到参数的映射规则

常用映射关系如下：

• vertical、poster、cover image、mobile cover、social card → aspect_ratio: 9:16
• square、avatar、icon、social post → aspect_ratio: 1:1
• landscape、wide banner、wallpaper、hero image → 选择一个受支持的宽幅比例，如 16:9
• give me a few options、multiple versions、more variations → 增加 image_number
• make it clearer、higher quality、higher resolution → 选用所选模型支持的最高 resolution
• use another model、check supported models、switch model → 提交前先运行 models-image.js

模型查询工作流

当用户提出更换模型，或请求可能不受支持的参数时：

1. 识别预期模式：text_to_image 或 image_to_image。
2. 首先运行对应版本的 models-image.js 命令。
3. 仅保留该模型实际支持的 image_number、aspect_ratio 与 resolution 取值。
4. 若多个模型均适配，推荐一个简洁默认项；除非用户明确要求对比，否则避免直接输出原始元数据。
5. 若支持情况不明，须明确说明，并在付费调用前使用 --dry-run 或安全模型查询进行验证。

提交前确认块

执行付费运行前，需展示简洁的确认块，列出最终请求载荷参数。

准备生成图像

- mode: `image-to-image`
- model: `WERYAI_IMAGE_2_0`
- image_number: `1`
- aspect_ratio: `9:16`
- resolution: `default`
- image: `https://example.com/input.png`
- prompt: `将这幅肖像重绘为电影级编辑风格图像，保持面部身份不变，采用精细布光、简洁构图、高级色彩分级与精修输出效果。`

请等待用户确认或提出修改意见后，再执行付费提交。

意图路由

在智能体（agent）环境中，默认路径为“图像优先提交 + 有界状态轮询”。

• 若用户仅提供 prompt，则路由至 text-to-image。
• 若用户提供 image 或 images，则路由至 image-to-image。
• 若用户已持有 taskId 或 batchId，则改用 status-image.js 查询状态，而非新建任务。
• 若用户询问支持的模型或参数，请在任何付费提交前先运行 models-image.js。
• 执行 submit-* 后，默认运行 status-image.js 轮询，直至图像就绪或达到 5 分钟超时上限。
• wait-image.js 仅在用户明确要求阻塞式单次结果时使用。
• 禁止无界状态轮询；默认轮询必须强制执行 5 分钟超时上限。
• 若任务仍在处理中，请及时向用户同步进度，但不得将任务 ID 视为最终交付成果。

推荐命令

# 默认异步提交
node scripts/submit-text-image.js --json '{"prompt":"一幅精致的编辑风格肖像"}'

# 轮询已有任务
node scripts/status-image.js --task-id 

工作流

1. 识别用户意图：text-to-image、image-to-image、状态查询或模型查询。
2. 收集 prompt；如有需要，再收集一个或多个公开的 https 参考图像 URL。
3. 应用默认配置：**WeryAI Image 2.0**（WERYAI_IMAGE_2_0）、image_number=1、aspect_ratio=9:16；除非用户另有要求。
4. 若用户希望使用自定义模型或非默认参数，且支持性存疑，则先运行 models-image.js。
5. 如需在付费提交前预览最终请求载荷，请使用 --dry-run。
6. 默认采用图像优先执行流程：
   • 第一阶段：submit-* 提交任务。
   • 第二阶段：运行 status-image.js 轮询，直至图像就绪或达 5 分钟超时上限。
   • 第三阶段：若超时，返回 taskId/batchId 并附超时说明，同时提供后续状态查询命令。
7. 禁止将状态查询视为无界循环；务必强制执行超时上限。
8. 使用 status-image.js 可安全地重新检查已有任务或批次。

输入规则

• prompt 是 text-to-image 与 image-to-image 请求的必填字段。
• 对于 image-to-image，接受 image 或 images；两者均会标准化为 API 所需的 images 数组格式。
• 每张参考图像来源可以是 http/https URL 或本地/文件路径（本地/非 http(s) 路径将先行上传）。
• 优先选用模型所支持的 aspect_ratio、image_number 与 resolution 取值。
• 禁止虚构未文档化的请求字段。

输出规范

所有命令均向 stdout 输出 JSON。成功响应对象可能包含：

• taskId、taskIds、batchId
• taskStatus
• images
• balance
• errorCode、errorMessage

面向用户的交付要求：

• 若存在图像 URL，至少返回一个用户可见的图像链接（例如 [Image](https://...)），或在支持环境下内联渲染图像；若生成多张图像，请依次使用 Markdown 图像语法全部渲染。
• 除图像外，还应附带关键生成参数（如可用）：model、aspect_ratio、image_number 与 resolution。
• 除非用户明确要求“先返回 ID”，否则不得仅以 taskId / batchId 作为唯一交付物。
• 若在完成前已达超时，应向用户返回 taskId 并询问是否需再次查询状态；切勿向用户展示原始 node 状态命令，仅限内部使用。

常见失败类型与恢复建议详见 references/error-codes.md。

完成标准（Definition Of Done）

当满足以下任一条件时，任务视为完成：

• 本地校验通过，CLI 侧无报错；
• 用户可至少看到一张生成图像或可用下载链接；
• 或 wait-image.js 达到终态结果并至少返回一个图像 URL；
• 或 status-image.js 轮询超时，并返回含任务追踪数据的明确“处理中”状态；
• 且输出内容明确指出图像 URL 是否存在；
• 当因超时仅获得任务追踪数据时，回复必须包含超时原因说明及明确的后续状态查询命令。

约束条件

• 不可假设所有图像模型均支持全部可选字段。
• 不可对参考图像直接使用本地文件路径（应由运行时自动上传）。
• 不可随意重跑 submit 或 wait，因为每次运行都可能创建新付费任务。
• 在智能体（agent）环境中，不可默认对可能阻塞会话的生成任务使用 wait-image.js。
• 不可将本技能扩展至超出 WeryAI 文档化 API 范围的通用图像编辑功能。

重跑行为

• submit-text-image.js 与 submit-image-to-image.js 非幂等；重复运行将创建新的付费任务。
• wait-image.js 同样非幂等：它先提交任务，再轮询至终态或超时。
• status-image.js、models-image.js 与 balance-image.js 可安全重跑。

参考资料

• 模型元数据与参数规则：references/api-models.md
• 错误处理指南：references/error-codes.md