在 Agent 中使用
让 Claude Code、OpenClaw 等智能体通过 tufty CLI 出图、出片。
tufty 为智能体设计：标准输出只有一个 JSON 信封，进度和提示写在标准错误，退出码区分成功、运行错误和用法错误。智能体只要能执行 shell 命令，就能调用 tufty.ai 的全部工作室工具。
快速上手指令
把下面这段话发给你的智能体：
用
npm install -g @tufty/cli安装 tufty CLI，运行tufty -h和tufty tools list了解可用工具，然后提醒我运行tufty login完成登录。
之后智能体通常会：
- 用
tufty <tool> -h或tufty tools describe <id>查看工具的输入、选项和价格； - 先加
--dry-run预估积分，得到你的确认后再正式运行； - 读取标准输出里的
result.outputs[].url，或用--save <dir>把成品存到本地。
登录
智能体里执行的命令通常没有交互终端。这时 CLI 不会弹出登录，而是直接返回 no_api_key。两种办法：
- 在自己的终端里运行一次
tufty login（推荐）。授权后密钥保存在~/.tufty/config.json，同一台机器上的智能体随后都能使用。 - 设置环境变量
TUFTY_API_KEY，适合 CI、容器或远程沙箱。密钥在 账户设置 → API 密钥 获取，以sk-开头。
详见 认证。
读取结果
{
"ok": true,
"result": {
"tool": "pet-dressup",
"runId": "3f6c2a1e-8b4d-4e7a-9c55-0d2b7e1f4a90",
"status": "completed",
"outputs": [
{ "type": "image", "url": "https://static.tufty.ai/.../result.png" }
]
}
}- 先看
ok：为true时读result，为false时读code、message和details。 - 只解析标准输出；标准错误里是进度、积分预估和提示，不要混在一起读。
- 只需要地址时加
--format url，标准输出每行一个成品地址。
更多见 输出模式。
必须处理的两类错误
| code | 智能体应当 |
|---|---|
insufficient_balance | 明确告诉用户积分不足（details.required 是这一步需要的积分），并给出充值链接 https://tufty.ai/dashboard/settings?tab=credits。不要自动重试。 |
unauthorized / no_api_key | 告诉用户到 https://tufty.ai/dashboard/settings?tab=api-keys 获取 API 密钥，运行 tufty auth set <key>（或 tufty login）后再继续任务。 |
其余错误码见 错误码。
长任务
视频通常需要几分钟。默认情况下 CLI 会一直等到任务完成（最长 --timeout 秒，默认 900）。如果智能体的单条命令有时长限制，改用 --no-wait 先拿到 runId，再用 tufty status <runId> --wait 取结果：
tufty image-to-video --still ./corgi-sweater.png --no-wait
tufty status 9b1d4c7e-2f3a-4d8b-a6e5-7c0f1e2d3b4a --wait见 异步与状态查询。
使用技能
支持技能的智能体（如 OpenClaw）可以安装 tufty 的工具技能，技能里写好了触发词、命令和错误处理。见 在 Agent 中使用技能。
排查
command not found: tufty：npm 全局目录不在智能体的PATH里，可改用npx @tufty/cli <command>。manifest_unavailable：连不上https://tufty.ai拉取工具清单，检查网络或代理。cli_version_too_low：运行npm install -g @tufty/cli@latest升级。