catsapi

CatsAPI Agent Skill

English

让支持 Agent Skills 的助手通过 CatsAPI / 猫图 AI 生成、编辑图片和生成视频。Skill 负责理解意图和交付，Python CLI 负责参数校验、费用预览、任务提交与恢复。

适用的 Agents

这不是 OpenClaw 专用插件。项目采用 Agent Skills 的 SKILL.md + 脚本/参考文件结构，面向能够读取技能、执行 Python 并访问网络的 Agent；不绑定宿主使用的某个大模型。

以下 Agent 均有官方 Skill 支持，可作为接入目标。列表确认的是宿主能力与安装目录，不代表本项目已在所有客户端、版本和运行环境中完成端到端实测。 官方文档核对日期：2026-08-31（DSH 于 2026-09-14 补充核对）；点击 Agent 名称查看安装细节。

表中是常用目录，不是完整搜索路径；自定义 profile、远程机器和容器以宿主配置为准。保留安装目录名 catsapi，与 SKILL.md 的 name 一致。应安装完整仓库，不能只复制 SKILL.md，否则会缺少脚本、模型快照或参考文档。

其他支持 Agent Skills 的 Agent 理论上也可接入；没有原生 Skill 加载器的 Agent，可以手动读取入口并调用 CLI，但需要自行关联目录和触发规则。完整运行还要求：

• 在 Agent 实际执行命令的环境中提供 Python 3.8+、CatsAPI Key，以及访问 CatsAPI 和结果下载地址的网络权限。
• 允许读取输入素材、执行脚本并写入输出文件；遵守宿主的信任、沙箱和审批规则。只读或纯聊天模式不能直接完成生成流程。
• 按宿主能力交付附件、媒体预览或文件链接；没有图像查看能力时不能声称做过视觉验收。

支持模型

共 10 个图片、4 个视频模型。CLI 也接受显示名，例如 --model "GPT Image 2.5"；支持名单不等于线上当前全部可用，使用 --list 核对线上状态。

安装与配置

仓库根目录就是 Skill 根目录，入口为 SKILL.md。克隆到宿主支持的 Skill 目录并按宿主配置启用，也可以保留独立仓库、在宿主中关联这个目录：

git clone https://github.com/maodeyu180/CatsAPI-Agent-Skill.git catsapi

将完整目录放到上表对应位置，或使用宿主官方的安装 / 目录关联功能，然后确认 catsapi 已被发现并启用。Hermes 的项目级安装还需要按官方文档信任该项目。使用时不需要把它作为主站的 Git submodule。

DSH 的项目级目录以最近的 Git 根目录为准；catsapi/SKILL.md 应直接位于扫描的 Skill 根目录下一层。需启用 DSH 的文件系统 Skill 加载能力，并让执行环境具备 Python、Shell 执行、联网权限和 CATSAPI_API_KEY。自定义 DSH_HOME、DSH_AGENTS_HOME 或 Skill 根目录时以配置为准。DSH 兼容性依据其官方加载格式核对，尚未在 DSH 中完整实测 CatsAPI 生图流程。

跨宿主注意：当前入口保留了 OpenClaw 的 metadata.openclaw 和 {baseDir} 写法。{baseDir} 指包含 SKILL.md 的绝对目录，不是 shell 变量；宿主不会自动展开时，先将命令中的占位符替换成实际目录，路径含空格时加引号。若宿主严格拒绝嵌套的 OpenClaw metadata，可仅在安装副本中移除这一可选项；CLI 不依赖它。无需更改生成逻辑，也不要为了执行脚本切换工作目录。

CLI 要求 Python 3.8+，仅用标准库。通过 CatsAPI 账户创建 API Key，并确保余额足够；不要把完整 Key 发到聊天中。配置环境变量或本地私密配置文件，详见 密钥指南。

export CATSAPI_API_KEY=cats-your-key
# 仅自建部署需要覆盖，默认 https://catsapi.com
export CATSAPI_BASE=http://localhost:8000

python3 scripts/catsapi.py --check

使用逻辑

直接告诉助手需求即可，例如：

• “用 Seedream 5 Pro 把这张产品图换成白色背景，其他不动。”
• “查一下 Gemini Omni Flash 做 6 秒竖屏视频多少钱，先不要生成。”
• “用 Grok Imagine Image 2 出 2 张方图，预算上限以我确认的报价为准。”
• “刚才的任务超时了，继续查原任务，不要重新生成。”

助手区分查询、创作、编辑和恢复；不先强制展示模型菜单，不改写要求原样保留的文字，不默认升级分辨率。生成前校验参数并查看实际报价；预算不明的批量、视频或明显升级会先确认。

脚本每次提交前都会重新预估并检查余额和 --max-coins。这是提交前保护，不是服务端原子锁价；0 表示不设上限。超时、断线或下载失败时保留任务 ID，用 --resume 继续，不能盲目重试生成。

CLI 示例

以下查询和预检不消耗生成额度；--cost 会联网，离线命令不会读取 Key：

python3 scripts/catsapi.py --list --type image --offline
python3 scripts/catsapi.py --info geminiOmniFlash --type video --offline

python3 scripts/catsapi.py --generate --type image \
  --model seedream5Lite --prompt "窗边的橘猫" \
  --param imageSize=landscape_16_9 --dry-run

python3 scripts/catsapi.py --generate --type image \
  --model Midjourney --prompt "水彩风格的橘猫 --stylize 200" \
  --param version=v7 --param aspectRatio=3:4 --mode fast --num 1 --dry-run

python3 scripts/catsapi.py --cost --type video \
  --model seedance20Mini --resolution 720p --duration 6

--dry-run 校验参数和数量，但不读取图片内容、不检查线上可用性、不写文件。真实生成需移除它，并使用已接受的花费上限：

# N 替换为用户已确认的猫币上限；此命令会提交付费任务
python3 scripts/catsapi.py --generate --type video \
  --model geminiOmniFlash --prompt "橘猫走过花园" \
  --duration 6 --param aspectRatio=9:16 --max-coins N --no-wait --json

# 用上一条命令返回的 ID 继续等待并下载，不创建新任务
python3 scripts/catsapi.py --resume TASK_ID --json

默认下载到运行命令时所在目录的 catsapi-output/；用 -o 指定文件名，已有文件会加序号而不是覆盖。宿主用原生附件、媒体预览或本地文件链接交付，不依赖特定 message 工具。

完整命令、JSON 输出与错误恢复见 CLI 参考。

参数与输入边界

• GPT Image 2 / 2.5：20 档尺寸、最多 16 张参考图。2.5 支持 1–4 张输出，默认 Flare / auto / 1024x1024；质量按 low / auto / medium / high / xhigh / max 排列，提示词最多 10000 字符。
• 2.5 精细变体用 --param variant=sunburst，透明 PNG 用 --param background=transparent（也可选 auto / opaque）。Sunburst 同质量、同尺寸按 Flare 单张价的 1.25 倍四舍五入收费；CLI 向服务端传递变体查询报价并检查 --max-coins，不本地另乘倍率。
• Nano Banana 2：最多 14 张参考图。Nano Banana 2 / Pro 默认开启联网搜索，可用 --param enableWebSearch=false 关闭。
• Seedream 5 Lite / Pro：用 imageSize，最多 4 张参考图；可传数字 seed。不支持独立的 resolution、quality 或 aspectRatio 字段。
• Grok Imagine Image 2：用 aspectRatio，最多 1 张参考图；与 GrokImage 是不同模型。
• Midjourney：仅文生图，默认 version=v7、aspectRatio=1:1、processMode=fast；版本可选 v7 / v6 / niji 6，提供 7 种比例和 fast / turbo / relax 处理模式。--mode 对应 processMode，负面提示词用 --param negativePrompt=...。每次固定返回 4 张、按次计费，--num 保持 1；不接收参考图，不提供分辨率、质量或提示词重写。
• Seedance 2.0 / Mini：默认 reference / 480p / 8 秒。Mini 没有 mode，不能传 fast。
• 两个 Seedance 的起始图 → 参考图 → 结束图合计最多 4 张，仅作参考，不保证严格首尾帧。主站 schema 写 9 张，但 worker 仍只保留 4 张，CLI 按实际限制拒绝超限请求。
• Gemini Omni Flash：5–10 秒，16:9 / 9:16，可选单张起始图；不提供分辨率或质量档位。
• 图片输入只接受 JPG / PNG / WEBP，单张不超过 10 MB。当前 CLI 不提供视频或音频参考输入。

详见 图片模型、视频模型 和 参数推断。

维护与验证

scripts/model_catalog.py 集中维护支持名单和别名。参数快照从主站生成，不手工维护另一份价格表：

python3 scripts/build_capabilities.py \
  --image-models /path/to/backend/app/image_models.json \
  --video-models /path/to/backend/app/abacus_video_models.json \
  -o data/capabilities.json

也可用 --from-api https://catsapi.com -o data/capabilities.json 读取线上公开 schema。价格始终以执行时 --cost 返回为准。

在项目 Python 环境运行 python -m unittest discover -s tests -v。测试模拟媒体和网络，覆盖支持名单、请求参数、费用保护、离线预检、恢复和交付；不读取真实 Key、不创建付费任务。不能替代上游模型的实际出图验证。

本次交互设计的参考与取舍见 设计说明。目录按入口 SKILL.md、详细说明 references/、实现 scripts/、快照 data/ 和离线测试 tests/ 分层。

相关项目与许可

• CatsAPI 主站
• ComfyUI_Catsapi — 同一主站的 ComfyUI 节点
• Apache License 2.0