# catsapi

Adopt this skill: https://proskills.md/skills/other/maodeyu180-openclaw-catsapi-skill

Page: https://proskills.md/skills/other/maodeyu180-openclaw-catsapi-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 6831
upstream: https://github.com/maodeyu180/openclaw_catsapi_skill/blob/HEAD/SKILL.md

````text
---
name: catsapi
description: "Create or edit images and generate videos through CatsAPI. Use for CatsAPI creative requests, model/parameter discovery, cost or balance checks, and recovering existing generation tasks. Respect an explicitly chosen different provider; do not route unrelated image analysis or repository maintenance into generation."
metadata: {"openclaw":{"emoji":"🐱","homepage":"https://catsapi.com","requires":{"bins":["python3"]},"primaryEnv":"CATSAPI_API_KEY"}}
---

# CatsAPI 创作助手

入口：`python3 {baseDir}/scripts/catsapi.py`。只依赖 Python 标准库。`{baseDir}` 是包含本文件的绝对目录；宿主不自动展开时先替换为实际路径，并给含空格的路径加引号。
支持 10 个图片模型、4 个视频模型；完整参数在 `data/capabilities.json`。CLI 负责校验与调用，宿主 Agent 负责理解需求与选择模型，不额外调用 LLM。

使用用户当前语言，简洁说明结果。可以友好，但不强制喵系口吻、中文、固定话术或交付后的追问。

英文会话请求传 `--locale en`，中文传 `--locale zh`；不要因界面语言变化而擅自翻译用户的提示词或图片文字。

## 先分清用户要什么

- 只问模型、参数、费用、余额或状态：只查询，不创建生成任务。
- 要生成：明确图片/视频、数量、输入素材、必须保留的文字/主体、画幅及预算；已给出的信息不要再问。
- 要编辑：先用宿主可用能力查看用户指定的图片，保留未要求更改的主体、构图、文字和风格。没有素材时不要假装已经看到。
- 要续做：找已有任务 ID 或已交付文件。超时、断线、下载失败都不意味着需要重新生成。
- 用户点名模型时按支持名单使用；未点名时按对应模型指南选一个默认，不先弹完整菜单。只有用户要比较/选择，或缺失信息会改变结果时才询问。

## 按需读取

| 需要解决的问题 | 读取 |
| --- | --- |
| 选图片模型、图片参考限制 | [image-models.md](references/image-models.md) |
| 选视频模型、起始帧/参考图差异 | [video-models.md](references/video-models.md) |
| 从自然语言推断画幅、参数和编辑约束 | [parameter-inference.md](references/parameter-inference.md) |
| 命令细节、离线预检、费用、异步/恢复、JSON | [cli-reference.md](references/cli-reference.md) |
| 第一次配 Key 或鉴权失败 | [api-key-setup.md](references/api-key-setup.md) |
| 媒体交付、超时/下载失败、错误处理 | [output-delivery.md](references/output-delivery.md) |

不需要为每次简单查询读取所有文件。明确模型后用 `--info MODEL --type image|video --offline` 获取该模型的精简 schema；只有需要核对线上可用性或最新参数时才去掉 `--offline`。

## 创作流程

1. **拟定请求。** 尊重指定模型、原始提示词、准确文字、输入图片和数量。不擅自加图、切换模型、提高分辨率或重写用户要求原样使用的提示词。默认 `rewritePrompt=false`。
2. **预检。** 新组合或复杂参数先用 `--generate ... --dry-run`。它只检查参数/数量，不读取 Key、不联网、不编码图片、不写文件；不代表媒体内容或线上可用性已验证。枚举和类型由脚本校验，不猜字段。
3. **核对花费。** 用相同模型/参数/数量执行 `--cost`，读取实际返回值，不引用文档旧价格。告诉用户总价。已有明确生成授权且在已知预算内时可继续；批量、视频、明显升级成本而预算不明时先确认花费上限。不能把“看看多少钱”当成生成授权。
4. **只提交一次。** `--generate ... --max-coins N` 会再次预估并阻止超限/余额不足的请求；N 用用户允许的上限，没有更宽预算时用本次已接受报价。此保护是提交前检查，不是服务端原子锁价。
5. **等待或恢复。** 短任务可直接等待。长任务用 `--no-wait --json` 拿到任务 ID，再用 `--resume TASK_ID --json` 等待和下载。保存任务 ID；恢复命令不会创建新任务。遇到未知提交结果，不自动重试 POST，先查网页任务记录。
6. **检查并交付。** 检查文件存在、数量和可查看的视觉结果；明确说明不能保证的部分。报告实际成本，交付所有文件。不要为弥补输出质量或数量不足自动发起额外付费任务。

## 常用入口

```bash
# 只查本地支持的模型，不需要 Key
python3 {baseDir}/scripts/catsapi.py --list --type image --offline

# 只预检，不付费；Seedream 用 imageSize，不是 aspectRatio
python3 {baseDir}/scripts/catsapi.py --generate --type image \
  --model seedream5Lite --prompt "窗边的一只橘猫" \
  --param imageSize=landscape_16_9 --dry-run

# 查已有任务 / 恢复等待与下载；都不会重新生成
python3 {baseDir}/scripts/catsapi.py --status TASK_ID
python3 {baseDir}/scripts/catsapi.py --resume TASK_ID --json
```

## 不可忽略的边界

- Midjourney 仅文生图，每次固定返回 4 张、按次计费，`--num` 必须为 1；下载并交付全部结果。版本、比例、处理模式分别通过 `version`、`aspectRatio`、`processMode` 传入，不用 prompt 中的参数标记覆盖；不接收参考图，也不发送 `rewritePrompt`。更多行内标记规则见图片模型指南。
- GPT Image 2.5 使用 `gptImage25`，默认 `variant=flare`、`quality=auto`；Sunburst 用 `--param variant=sunburst`。预览与提交必须使用相同变体，以服务端报价保护预算，不在客户端另乘价格倍率。
- 两个 Seedance 都只用 `inputMode=reference`；Mini **没有** `mode`。起始图 → 参考图 → 结束图合计最多 4 张，是参考素材，不保证严格首尾帧。schema 的 9 张尚未在主站 worker 全部生效。
- Gemini Omni Flash 只有 `duration=5..10` 和 `aspectRatio=16:9|9:16`，不要承诺或传入分辨率/质量档位。
- 当前客户端只接收 JPG/PNG/WEBP 图片输入。虽然上游 schema 里有视频/音频字段，本客户端没有开放这些输入；不能通过 `--param` 绕过。
- 密钥只由脚本读取环境变量/本地配置；不询问完整 Key、不把它写进聊天或命令行、不输出配置文件内容。设置问题按需读 Key 指南，不重复盘问已配置用户。
- 默认输出到当前工作目录 `catsapi-output/`；用户指定 `-o` 时服从指定路径，已有文件不覆盖。不要为了运行脚本切到 skill 目录。
- 交付适配宿主：有原生附件工具就用附件；支持本地媒体预览/文件链接就提供对应链接；否则给绝对路径并说明。不要假设一定有 `message`，不要固定回复 `NO_REPLY`，不要向用户暴露内部结果 URL。
````

## File: README.md
upstream: https://github.com/maodeyu180/openclaw_catsapi_skill/blob/HEAD/README.md

````text
# CatsAPI Agent Skill

[English](README_en.md)

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

## 适用的 Agents

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

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

| Agent | 项目 / 工作区安装目录 | 用户级安装目录 |
| --- | --- | --- |
| [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/) | `.hermes/skills/catsapi/`（需信任项目） | `~/.hermes/skills/catsapi/` |
| [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/skill/skill-filesystem/README.md) | `.dsh/skills/catsapi/` 或 `.agents/skills/catsapi/` | `~/.dsh/skills/catsapi/` 或 `~/.agents/skills/catsapi/` |
| [OpenClaw](https://docs.openclaw.ai/tools/skills) | `<workspace>/skills/catsapi/` | `~/.openclaw/skills/catsapi/` |
| [Claude Code](https://code.claude.com/docs/en/skills) | `.claude/skills/catsapi/` | `~/.claude/skills/catsapi/` |
| [Codex（CLI / IDE / 桌面本地任务）](https://developers.openai.com/codex/skills/) | `.agents/skills/catsapi/` | `~/.agents/skills/catsapi/` |
| [Cursor Agent](https://cursor.com/docs/skills) | `.cursor/skills/catsapi/` | `~/.cursor/skills/catsapi/` |
| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.gemini/skills/catsapi/` | `~/.gemini/skills/catsapi/` |
| [OpenCode](https://opencode.ai/docs/skills/) | `.opencode/skills/catsapi/` | `~/.config/opencode/skills/catsapi/` |
| [GitHub Copilot（CLI / IDE Agent 模式）](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills) | `.github/skills/catsapi/` | `~/.copilot/skills/catsapi/` |
| [Cline](https://docs.cline.bot/customization/skills) | `.cline/skills/catsapi/` | `~/.cline/skills/catsapi/` |
| [Windsurf / Devin Desktop（Cascade）](https://docs.devin.ai/desktop/cascade/skills) | `.windsurf/skills/catsapi/` | `~/.codeium/windsurf/skills/catsapi/` |

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

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

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

## 支持模型

| 类型 | 模型 key | 名称 |
| --- | --- | --- |
| 图片 | `gptImage25` | GPT Image 2.5 |
| 图片 | `gptImage2` | GPT Image 2 |
| 图片 | `nanoBanana2` | Nano Banana 2 |
| 图片 | `nanoBananaPro` | Nano Banana Pro |
| 图片 | `flux2Pro` | FLUX.2 Pro |
| 图片 | `grokImagineImage` | GrokImage |
| 图片 | `seedream5Lite` | Seedream 5 Lite |
| 图片 | `seedream5Pro` | Seedream 5 Pro |
| 图片 | `grokImagineImage2` | Grok Imagine Image 2 |
| 图片 | `midjourney` | Midjourney |
| 视频 | `seedance20` | Seedance 2.0 |
| 视频 | `grokImagineVideo` | GrokImageVideo |
| 视频 | `seedance20Mini` | Seedance 2.0 Mini |
| 视频 | `geminiOmniFlash` | Gemini Omni Flash |

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

## 安装与配置

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

```bash
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 发到聊天中。配置环境变量或本地私密配置文件，详见 [密钥指南](references/api-key-setup.md)。

```bash
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：

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

```bash
# 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 参考](references/cli-reference.md)。

## 参数与输入边界

- 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 不提供视频或音频参考输入。

详见 [图片模型](references/image-models.md)、[视频模型](references/video-models.md) 和 [参数推断](references/parameter-inference.md)。

## 维护与验证

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

```bash
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、不创建付费任务。不能替代上游模型的实际出图验证。

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

## 相关项目与许可

- [CatsAPI 主站](https://catsapi.com)
- [ComfyUI_Catsapi](https://github.com/maodeyu180/ComfyUI_Catsapi) — 同一主站的 ComfyUI 节点
- [Apache License 2.0](LICENSE)
````