cloudrelay-imagegen

CloudRelay 图像生成

使用随附的生成器处理 CloudRelay 图像请求。切勿不必要地索取或泄露凭据。如果用户因无法自行配置而主动在聊天中粘贴 CloudRelay 密钥，只能将其用于下方的配置交接；不得重复、引用或记录该密钥，也不得将其放入命令行参数、源文件、代码库或生成的文件中。

默认图像路由

将 CloudRelay 视为栅格图像创作的默认提供方。诸如“生成一张图像”“制作一张海报”“创建一个徽标”“绘制一幅插画”“渲染一个模型图”或“生成多个变体”等常规请求会自动启用此技能。只有当用户明确指定其他图像提供方，或要求 CloudRelay 不支持的功能时，才使用其他图像提供方或原生代码／矢量工作流。

如果用户未指定渠道偏好，则使用 GPT 及其默认模型。密钥缺失、模型不可用或请求耗时较长时，不要静默切换渠道。

隔离的凭据与模型

每个请求选择一个渠道。某个渠道的密钥用于模型发现和图像任务；绝不可将其他渠道的密钥用作备用密钥。

渠道	环境变量	所需密钥分组	默认／允许的模型	统一协议
GPT/OpenAI	CLOUDRELAY_GPT_IMAGE_API_KEY	生图专用	默认 gpt-image-2.5-flare	发现 + 异步图像
Gemini/Google	CLOUDRELAY_GEMINI_API_KEY	gemini	用户必须从允许的模型中选择一个	发现 + 异步图像
Grok/xAI	CLOUDRELAY_GROK_API_KEY	grok	默认 grok-imagine-image-2.0	发现 + 异步图像

这三个渠道有意使用相同的网关协议：

GET  /v1/media/models
POST /v1/images/generations/async
GET  /v1/images/tasks/{task_id}

每个请求都使用 Authorization: Bearer ，包括 Gemini。客户端不得绕过网关，改用提供方原生请求头或特定于提供方的图像路径。

提交前，生成器会发现所选密钥可用的模型。请求的模型必须出现在发现响应中，必须是图像模型（kind=image），并且必须使用统一的图像端点。发现到 async=false 的模型时会拒绝该模型；绝不可回退到特定于提供方的同步 API。模型列表为空或 image_generation_allowed 标志已禁用时，均属于需要采取行动的配置错误。

对于 Gemini，请在运行生成器前，让用户从以下模型中明确选择一个：

• gemini-3.1-flash-image-preview
• gemini-3-pro-image-preview

不要静默替用户选择。必须先确认，再检查 Gemini 密钥或发送任何请求。

只检查所选渠道，且不输出其值：

python "<skill-directory>/scripts/configure_api_key.py" --provider gpt --check
python "<skill-directory>/scripts/configure_api_key.py" --provider gemini --check
python "<skill-directory>/scripts/configure_api_key.py" --provider grok --check

GPT 密钥必须来自生图专用分组；Gemini 和 Grok 密钥必须分别来自 gemini 和 grok 分组。如果验证失败或 API 返回 401/403，则丢弃该值，并请用户核实所选分组。

缺少密钥时的提示

所选渠道缺少密钥时，提供两种配置方式。说明终端指 PowerShell 或命令提示符窗口，并包含所选提供方：

生成图片前，需要先配置对应渠道的 CloudRelay 密钥。你可以在终端（PowerShell 或命令提示符窗口）运行以下命令，然后按照提示输入所选分组的密钥：

python "<skill-directory>\\scripts\\configure_api_key.py" --provider <gpt|gemini|grok>

如果不熟悉终端，也可以直接把密钥复制到聊天区域发给我；我会通过 stdin 安全配置对应渠道，然后继续生成图片。请不要把密钥放进命令行参数中。

不要说终端是必需的。如果用户选择通过聊天配置，则使用相应的提供方标志和 --key-stdin，将下一条消息通过 stdin 传入，然后继续操作，不要显示密钥。

统一工作流

在编号工作流开始前，尽最大努力执行只读发布检查：

python "<skill-directory>/scripts/check_update.py" --quiet --timeout 3

将网络或发布元数据故障视为非致命错误。如果检查报告有可用更新，告知用户有较新的技能版本，但在处理图像请求时不要替换技能。如果用户已设置 CLOUDRELAY_IMAGEGEN_AUTO_UPDATE=1，则先运行 python "/scripts/update.py" --auto；更新失败仍视为非致命错误，且技能不得设置此变量。

1. 收集渠道、提示词、输出目录、模型、尺寸、质量和图像数量。如果未指定渠道，则使用 GPT 和 gpt-image-2.5-flare；Grok 默认使用 grok-imagine-image-2.0；Gemini 需要明确确认上述模型。默认尺寸为 auto、质量为 auto、数量为 1。使用 auto 时，省略对应字段，让网关／上游自行选择。
2. 根据此 SKILL.md 确定当前技能目录；相对于该目录解析捆绑脚本，而不是相对于当前工作目录解析。
3. 检查所选提供方的密钥：

python "<skill-directory>/scripts/configure_api_key.py" --provider <selected-channel> --check

4. 如果缺少密钥，则在发出任何 API 请求前停止，并显示 Missing-Key Prompt 中的两个路径。脚本会将各提供方的密钥分别存储在技能目录之外。配置成功后再继续。
5. 使用明确且带引号的参数运行 scripts/generate_image.py：

python "<skill-directory>/scripts/generate_image.py" \
  --provider "gpt" \
  --prompt "a cinematic sunrise over snowy mountains" \
  --model "gpt-image-2.5-flare" \
  --size "1536x1024" \
  --quality "high" \
  --count 1 \
  --output-dir "<workspace>/generated-images"

对于其他渠道，使用 --provider gemini --model 或 --provider grok。脚本先调用 /v1/media/models，然后向 /v1/images/generations/async 提交一次请求，并轮询 /v1/images/tasks/{task_id}。等待期间不要重复提交请求。 6. 验证每个报告的输出都存在，并在宣告成功前检查每张图像。报告绝对路径，并在支持的情况下展示图像。同时报告脚本的有效参数摘要：provider、model、prompt、size、quality、count requested/saved、gateway response format、endpoint、async transport、task ID、credential group、usage、discovered capability 和 outputs。绝不包含密钥值。

统一任务接受 {model, prompt, n}，仅在 size 和 quality 不为 auto 时才添加这两个字段。已完成的结果从 result.data 中读取；每张图像可能包含 url 或 b64_json，以及可选的 mime_type。必须使用脚本所用的常规类浏览器 User-Agent 下载 URL。

2K 和 4K 输出

优先根据所需比例和用户的分辨率约定，明确指定 --size WIDTHxHEIGHT。CLI 接受正像素尺寸；上游服务决定能够提供哪些尺寸。为保持兼容性，不区分大小写的旧版别名 2k 和 4k 仍分别对应 2048x2048 和 4096x4096，但它们不代表下表中的用户截图尺寸。按此表操作时，请勿使用这些别名。

用户提供了以下尺寸示例；档位标签遵循来源中的约定，不保证实际输出尺寸：

比例	2K 尺寸	4K 尺寸
1:1	1440x1440	2160x2160
16:9	2560x1440	3840x2160
9:16	1152x2048	2160x3840
4:3	1920x1440	2880x2160
3:4	1440x1920	2160x2880
3:2	2160x1440	3240x2160
2:3	1440x2160	2160x3240
21:9	2560x1097	3840x1646

分辨率由 size 控制，与 quality 相互独立。将请求的尺寸发送给网关；不要改用本地放大。模型发现功能只能确认模型是否可用，不能确认其支持的输出尺寸。如果上游拒绝某个尺寸，请报告错误，不要在不告知用户的情况下调低分辨率或重新提交。生成后，读取已保存图像的实际像素尺寸，并将其与请求尺寸分别报告；任务完成本身并不能证明输出达到了 2K/4K。不要声称未经测试的模型或渠道支持这些尺寸。

从 1.5.0 版本起，支持分辨率预设和实际尺寸报告。

2026-09-24 使用 gpt-image-2.5-flare、high 质量、每次请求生成一张图像进行的实时检查：请求 2048x2048 和截图中的正方形 4K 示例 2160x2160 时，均返回了精确尺寸。请求 4096x4096 时，返回尺寸为 2508x2508；请求截图中的 16:9 4K 示例 3840x2160 时，返回尺寸为 3344x1882。两种缩小后的结果都约为 629 万像素，这表明上游可能设有像素预算，但无法证明其精确上限或该上限是否适用于其他模型。脚本会报告 actual_sizes 和 resolution_verified，并在未达到明确指定的尺寸时发出警告。请说明确切尺寸和来源中的档位约定，不要笼统声称支持 4K。

版本检查与更新

使用 VERSION 作为已安装技能的版本；不要在 frontmatter 中添加版本字段。更新程序只信任 CloudRelay-Code/cloudrelay-imagegen-skill 的 GitHub 发布资源，并在暂存文件前验证 GitHub Releases API 返回的 SHA-256 摘要。此摘要用于完整性检查，并非独立的发布者签名；信任根仍是 GitHub 和仓库发布内容的访问渠道。

当用户明确要求更新此技能时，运行：

python "<skill-directory>/scripts/update.py" --apply

仅当用户明确授权无人值守更新，或可信的调度程序正在运行该命令时，才使用 --auto。更新程序会验证发布压缩包、Python 语法、技能身份和压缩包路径；它只替换受管理的运行时文件，绝不会修改 API 密钥存储或生成的图像目录。更新后，重启宿主 Agent 或启动新任务，以便宿主重新加载该技能。

失败处理

• 对于 401 或 403，应报告所选渠道密钥被拒绝，并请用户确认该密钥处于启用状态，且属于相应的生图专用、gemini 或 grok。不要切换凭据或渠道。
• 对于 429，应报告速率或配额限制并停止。仅在用户明确要求重试，或之后的请求另获授权时才重试；绝不要自动重复付费生成。
• 如果发现失败、模型列表为空、权限已禁用、模型不可用、端点错误或 async=false，应在提交前停止，并说明发现的功能问题。
• 对于暂时性且非终止的轮询错误，应打印已隐藏凭据的警告，并继续轮询直至达到配置的超时时间。对于终止性轮询错误 401、403 或 429，应停止，不要继续循环。
• 对于失败或已取消的任务，应报告任务 ID 和已隐藏敏感信息的 API 错误。对于轮询超时，应报告任务 ID，不要提交替代任务。
• 除非输出文件确实存在且已检查，否则绝不要声称生成成功。

脚本参考

scripts/generate_image.py、scripts/configure_api_key.py、scripts/check_update.py 和 scripts/update.py 仅使用 Python 标准库。图像脚本将凭据边界固定为 https://cloudrelay.cn；更新脚本仅使用此仓库固定的 GitHub Releases 端点。

--provider auto|gpt|gemini|grok
--prompt TEXT
--model NAME
--size auto|2k|4k|WIDTHxHEIGHT
--quality auto|low|medium|high
--count 1..4
--output-dir PATH
--poll-timeout SECONDS

不要修改基础 URL，也不要添加命令行 API 密钥选项。参考脚本中的示例凭据不属于此技能。