zeroHub Image API Skill

什么时候用

当用户希望通过 zeroHub API 生成图片、查询账户余额、验证 sk-img-... API Key、轮询生成任务，或把生成结果保存到本地目录后再发送时，使用本 skill。

本 skill 面向通用分发场景设计：API Key 由用户自行提供，生成结果通过 zeroHub 返回的 URL 获取，并保存到用户指定的输出目录。

关于 zeroHub

zeroHub 是一个面向开发者和自动化工作流的图片生成 API 服务，提供统一的图片生成接口、任务查询接口和余额查询接口，适合在 Agent、脚本、工作流或业务系统中接入图像生成能力。

• 官网：https://zerohub.zhyy.ltd
• API 文档：https://zerohub.zhyy.ltd/docs

功能

• 查询 zeroHub 账户余额；
• 提交文生图 / 图生图生成任务；
• 轮询任务状态直到成功、失败或超时；
• 自动处理 zeroHub 返回的相对图片 URL；
• 将生成图片下载到用户指定目录；
• 输出结构化 JSON，方便后续发送文件或继续自动化处理。

服务信息

• Base URL 默认：https://zerohub.zhyy.ltd
• API 文档：https://zerohub.zhyy.ltd/docs
• 认证方式：Authorization: Bearer \x3CZEROHUB_API_KEY>
• 默认模型：gpt-image-2
• 主要接口：
  • GET /v1/user/balance
  • POST /v1/images/generations
  • GET /v1/images/query/{task_id}

安全要求

1. 不要在 skill、脚本、日志或回复中写入真实 API Key。
2. API Key 应由用户通过环境变量 ZEROHUB_API_KEY 提供。
3. 执行 shell 命令前建议使用 set +x，避免命令回显泄露 Key。
4. 生成任务可能产生费用；提交生成前应确认用户确实想要生成图片。
5. 下载目录应由用户明确指定；不要擅自写入不确定的位置。
6. 如果用户没有提供 API Key，应提示其先配置 ZEROHUB_API_KEY。

推荐流程

1. 查询余额

set +x
export ZEROHUB_API_KEY='\x3Cuser-provided-key>'

./scripts/zerohub_image_public.py balance

2. 生成图片并下载到指定目录

set +x
export ZEROHUB_API_KEY='\x3Cuser-provided-key>'

./scripts/zerohub_image_public.py generate \
  --prompt 'A small red lobster mascot sitting on a lotus leaf, cute sticker style' \
  --size '1:1' \
  --quality low \
  --output-dir './outputs' \
  --download

脚本会：

1. 提交图片生成请求；
2. 解析返回的 task_id；
3. 按间隔轮询任务状态；
4. 成功后读取 images / preview_images；
5. 将相对 URL 补全为完整 URL；
6. 下载图片到 --output-dir；
7. 输出 JSON，包含 task_id、status、images、downloaded_files 等字段。

3. 只下载已有图片 URL

./scripts/zerohub_image_public.py download \
  --output-dir './outputs' \
  'https://zerohub.zhyy.ltd/api/image-gen/v1/images/assets/xxx'

常用参数

generate

• --prompt：生成提示词，必填。
• --model：模型名，默认 gpt-image-2。
• --size：图片比例或尺寸，默认 1:1。
• --quality：质量，可选 auto、low、medium、high，默认 low。
• --images：参考图 URL，支持多个。
• --max-wait：最长等待秒数，默认 180。
• --interval：轮询间隔秒数，默认 5。
• --download：生成成功后下载图片。
• --output-dir：下载目录，使用 --download 时必填。
• --no-preview-download：只下载正式图片，不下载预览图。

download

• --output-dir：下载目录，必填。
• --prefix：输出文件名前缀，默认 zerohub-image。
• urls：一个或多个图片 URL。

发送结果

脚本输出的 downloaded_files 是一个数组。每一项通常包含：

{
  "ok": true,
  "url": "https://...",
  "path": "./outputs/zerohub-task-1.png",
  "filename": "zerohub-task-1.png",
  "content_type": "image/png",
  "size": 123456
}

后续可以使用当前运行环境提供的文件发送能力，把 path 对应的本地文件发送给用户。

注意

• zeroHub 返回的图片可能是相对 URL，例如 /api/image-gen/v1/images/assets/\x3Ctoken>；脚本会自动基于 ZEROHUB_BASE_URL 补全。
• 可以通过环境变量 ZEROHUB_BASE_URL 覆盖默认服务地址。
• 下载目录会自动创建。
• 文件名会进行安全清理，避免路径穿越。
• 如果下载失败，JSON 中会保留失败 URL 和错误信息，方便用户手动处理或重试。