エージェントで使う

Claude Code、OpenClawなどのエージェントに、tufty CLIで画像や動画を作成させます。

tuftyはエージェントでの利用を前提に作られています。標準出力にはJSONエンベロープが1つだけ出力され、進行状況やヒントは標準エラー出力に書き出されます。終了コードで成功・実行時エラー・使い方の誤りを区別できます。シェルコマンドを実行できるエージェントなら、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>でファイルをローカルに保存する。

自分のターミナルで一度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を付けると、標準出力に生成物のURLが1行に1つずつ出力されます。

詳しくは出力モードを参照してください。

エージェントが必ず処理すべき2つのエラー

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）。エージェント側で1コマンドあたりの実行時間に制限がある場合は、--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のツールスキルをインストールできます。スキルには起動のきっかけとなる言葉、コマンド、エラー処理があらかじめ記述されています。詳しくはSkillsを参照してください。

トラブルシューティング

command not found: tufty：npmのグローバルbinディレクトリがエージェントのPATHに含まれていません。代わりにnpx @tufty/cli <command>を使ってください。
manifest_unavailable：CLIがhttps://tufty.aiに接続できず、ツールマニフェストを読み込めませんでした。ネットワークやプロキシの設定を確認してください。
cli_version_too_low：npm install -g @tufty/cli@latestでアップグレードしてください。