clipcat

Clipcat CLI

このスキルは意図的に短くしています。詳細なフラグやサポートされている値については CLI 自体を参照してください。常に clipcat -h と clipcat <subcommand> -h を主要なリファレンスとして扱ってください。-h で最新情報を確認できないのはモデルカタログだけです。モデルはリリースの合間にも追加・削除されるため、現在利用できるモデル、解像度、長さについては clipcat models が正確な情報源です。

インストール

まず clipcat --version を実行してください。バージョンが表示された場合は clipcat がインストール済みなので、API キーの設定に進んでください。コマンドが見つからない場合は、お使いのプラットフォームに合わせてインストールしてください。

macOS / Linux / Git Bash：

curl -fsSL https://clipcat.ai/cli | bash

Windows（PowerShell、bash なし）：

irm https://clipcat.ai/cli.ps1 | iex

続いて API キーを設定してください（以下を参照）。後で更新する場合は clipcat update を実行してください（インストーラーが再実行されます。保存済みの設定は保持されます）。

Windows サンドボックスに関する注意（Codex など）

Windows へのインストール時に SEC_E_NO_CREDENTIALS、AcquireCredentialsHandle、0x8009030E、「The underlying connection was closed」、または「基础连接已经关闭」というエラーが発生した場合は、Windows TLS スタック（Schannel）が認証情報を開けない制限付きサンドボックス（Codex Windows サンドボックスなど）を使用しています。その環境では Invoke-WebRequest とシステムの curl.exe がどちらも失敗します。インストーラーは Node を経由したダウンロードを自動的に再試行します（Node の OpenSSL は Schannel を迂回します）。そのため、サンドボックスに Node をインストールすると通常は解決します。それでも失敗する場合は、インストールコマンドをユーザーに提示し、サンドボックス外の通常の PowerShell で実行するか、サンドボックス外での実行を承認するよう依頼してください。別のコマンドで再試行し続けないでください。

API キー

ローカルの設定ファイルでキーを設定してください。これが唯一確実な方法です。

clipcat config --api-key <your-key> --base-url https://clipcat.ai

キーは https://clipcat.ai/workspace?modal=settings&tab=apikeys で取得してください。CLIPCAT_API_KEY 環境変数よりも設定ファイルを優先してください。サンドボックス内のエージェント（Codex など）は、名前に KEY／SECRET／TOKEN を含む環境変数を除外するため、通常は環境変数を参照できません。（OpenClaw は CLIPCAT_API_KEY を自動的に設定します。設定されている場合は、設定ファイルより優先されます。）

この CLI の用途

clipcat は、すべての Clipcat AI 動画生成ワークフローを実行するためのローカルエントリーポイントです。

• TikTok の E コマースデータを照会します：クリエイター、商品、ショップ、動画、ライブ配信、検索
• バズ動画プロンプトライブラリから、すぐに撮影できる販売動画のプロンプトを生成します
• 自分の商品を使ってバズ動画を再現します
• 画像から商品動画を生成します
• 独自のプロンプトとアセットをそのままモデルに送信し、動画を生成します
• GPT Image 2 / GPT Image 2.5（Flare / Sunburst）を使って、テキストプロンプトから AI 画像を生成します。参照画像も任意で指定できます
• スクリプトを mp3 のナレーション（テキスト読み上げ、プリセット音声またはクローン音声）に変換します。再利用可能な参照音声として使用できます
• 動画を分析します（スクリプト、シーン、音楽）
• TikTok／Douyin の動画をダウンロードします
• 完成した動画を自分の TikTok アカウントに公開します（直接投稿または下書き受信箱）
• エージェントのプロンプトを、毎日または指定した曜日に自動実行するようスケジュールします
• 非同期タスクのステータスを照会します

エージェントのデフォルトワークフロー

1. まず clipcat -h を実行して、すべてのコマンドを確認します。
2. コマンドを使用する前に、clipcat <subcommand> -h を実行してフラグを確認します。
3. デフォルトでは JSON 出力を使用します。
4. replicate / product_video / generate / tiktok publish は、2 回の呼び出しで送信します。 1 回目の呼び出しでは料金は発生せず、何も作成されません。チェックリストと confirmId が返されます。チェックリストをユーザーに提示し、明示的な承認を待ってから --confirm <confirmId> を実行してください（「2 段階確認」を参照）。
5. いずれかのコマンドが標準エラー出力に更新通知（⬆ clipcat X is available … Run: clipcat update）を表示した場合は、clipcat update を 1 回実行してから続行してください。 最新バージョンを使用している場合は自動的に処理をスキップするため、安全に実行できます。

適切なコマンドの選択

TikTok E コマースデータ — エンティティコマンド

これらは名詞と動詞の形式のコマンドです：clipcat <entity> <verb>。動詞を一覧表示するには clipcat <entity> -h を、フラグを確認するには clipcat <entity> <verb> -h を実行してください。

• creator <list|rank|profile|enrich|trend|posts|sales-videos|lives|products|followers|following|region|milestones> — TikTok のクリエイター／インフルエンサー
• product <list|rank|detail|trend|reviews|live-comments|creators|videos|lives> — TikTok Shop の商品
• seller <list|rank|detail|trend|catalog|inventory|creators|videos|lives> — TikTok Shop のショップ
• video <list|rank|snapshot|sales|trend|comments|captions|products|hashtag> — TikTok の動画
• live detail — ライブ配信ルームの詳細（配信中のみ）
• find <creators|products|videos|lives|hashtags|music|photo|all> — キーワード／画像検索。find all は幅広く検索するためのフォールバックです。

データソースは 2 つあり、コマンド名によって使用するソースが決まります。 判断が必要な --mode フラグはありません。必要なデータに応じて選択してください。

必要なデータ	コマンド	取得できるデータ	取得できないデータ
クリエイターの最近の投稿	creator posts	公開されているすべてのクリエイター。新しい順	動画ごとの売上／GMV はありません
クリエイターのショッピング可能な動画	creator sales-videos	動画ごとの売上 + GMV。並べ替え可能	履歴データセットに含まれるクリエイターのみ
クリエイターの現在のプロフィール	creator profile	公開されているすべてのクリエイター	累計コマース指標はありません
複数クリエイターのコマース指標	creator enrich	一括取得（最大 10 件）。累計指標	収集済みのクリエイターのみ
1 本の動画の現在の状態	video snapshot	公開されているすべての動画	売上／GMV はありません
ID がすでにわかっている動画の売上	video sales	一括取得（最大 10 件）。売上 + GMV	収集済みの動画のみ
評価で絞り込めるレビュー	product reviews	評価フィルター、ページネーション	データがやや古くなっています
最新のコメント	product live-comments	最新のコメント。--region が必要	評価フィルターはありません
削除済みの商品を含むショップの履歴	seller catalog	売上 + GMV。並べ替え可能	現在掲載されている商品ではありません
ショップが現在掲載している商品	seller inventory	現在の情報。--region が必要	売上／GMV はありません

履歴データセットはすべてを網羅しているわけではありません（コストの都合で収集数に上限があります）。 そのため、sales／catalog／enrich 系のコマンドでは「未収集」となることがよくあります。 ライブ検索で取得した ID の場合、10 件中およそ 4〜6 件が該当します。… rank／… list から取得した ID は、仕様上データセットに含まれるため、ほぼ毎回結果が返ります。 ここで結果が空でも、「存在しない」のではなく「未収集」を意味します。再試行するのではなく、ライブコマンドで確認してください。エンドユーザーには offline/realtime という言葉を使わず、「履歴データ」と「最新データ」と表現してください。

ページネーション：各呼び出しでは 1 ページ分が返され、1 回分の料金が発生します。履歴データの list/rank コマンドでは --page／--page-size を使用します（--page-size の上限は 10 です。それを超える値は上限まで切り詰められ、レスポンスの pagination_corrected で通知されます。さらに行を取得するには --page 2、--page 3、…を指定してください）。ライブリストでは、前のページから返された --offset／--cursor／--scroll-param を使用します。ページごとにコマンドを繰り返して続きを取得してください（--max-pages は非推奨で、無視されます）。

2 つのデータソースでページネーション方式は異なります。 履歴データのコマンド（creator sales-videos、product reviews、seller catalog）はページ番号でページを指定します。一方、対応するライブコマンド（creator posts、product live-comments、seller inventory）はカーソルでページを指定するため、ページ番号をカーソルとして使うことはできません。ライブリストに --page を指定すると、CLI はそのコマンドを拒否します。古いクライアントから送信された場合、レスポンスには pagination_ignored が含まれます。これは、要求したページではなく、データソースの最初のページであることを意味します。元のページ番号でのページ取得をやめ、next に含まれるトークンを使って続けてください。ページ番号を繰り返すと同じ行が返され、再び 6 クレジットが請求されます。 空の結果も回答であり、失敗ではありません。 過去のデータセットはすべてを網羅しているわけではないため、空の結果は通常、「そのデータセットには含まれていない」という意味であり、「そのようなものは存在しない」という意味ではありません。その場合、レスポンスには try_instead が含まれ、もう一方のソース用のすぐに実行できるコマンドのほか、各ソースで得られる情報（ライブ：網羅的なデータ、販売数／GMVなし、過去データ：販売数／GMVと並べ替え、対象エンティティのみ）、および追加が必要なフラグが示されます。ソースの切り替えは別途課金される呼び出しです。これらのフィールドが必要な場合にのみ切り替えてください。同じ空のクエリを再試行しないでください。

エラーから再試行の要否がわかります。 失敗時には error_kind と retryable が含まれます。transient（レート制限または短時間の不調。同じコマンドを数秒後に再試行してください）、invalid_params（何が誤っているかメッセージに明記されています。フラグを修正し、同じ内容では決して再試行しないでください）、temporarily_unavailable（再試行しても解決しません。クエリを変更するか、時間をおいて再度試してください）。

クレジット不足：読み取りコマンドは1回につき6クレジットかかります（prompt search は3クレジットで、プランに含まれる無料枠を使い切った後にのみ課金されます）。残高がこれを下回ると、エラーが返され、データは返されません。

データクエリの手引き（詳細）：

• ID は推測せず、たどって取得してください。 まず検索し（<entity> list|rank、find …）、結果から ID を取得してから、詳細／トレンド／関連性の動詞を呼び出します。 一括処理の動詞では カンマ区切りの ID（--user-ids、--product-ids、 --video-ids、最大10件）を指定します。
• ID の取得元によって、回答に使えるコマンドが決まります。 find … （リアルタイム検索）で取得した ID は、あらゆる公開エンティティのものなので、その後はリアルタイムコマンド（ video snapshot、creator posts、creator profile）を使います。… rank／… list で取得した ID は、取得時点で履歴データセットに含まれているため、その後は video sales、creator sales-videos、creator enrich、seller catalog を使います。リアルタイム検索の ID をそのまま売上コマンドに渡すのは、空の結果にクレジットを浪費する最もよくある原因です。find videos の ID は、約10件中4件で売上データセットにありません。リアルタイムで見つけたものの売上数値が必要な場合は、収集されていないデータを何度も問い合わせるのではなく、その旨を明確に伝えてください。
• コマースで活動しているエンティティから関連性検索の起点を選んでください。 サブリソースの動詞 （creator products|lives、product creators|videos|lives、seller lives、 video products）は、活動の少ない ID に対して [] を返します。任意の行ではなく、 … rank または並べ替えた … list（売上／フォロワー数の上位）から起点を取得してください。そうしないと結果が空になることがあります。
• … rank には 最近の --date が必要です。 対象期間内の日付を指定してください。バックエンドが期間の基準日に自動で合わせます（週→その週の月曜日、月→その月の1日）。 期間が異なるデータを黙って返すことはありません。期間が終了していない場合や、データがまだ生成されていない場合（T+1、通常は正午以降）は、data: [] と period（requested／latest_available／previous。それぞれに anchor／start／end）が返され、再試行する正確な --date を示す hint が含まれます。同じ期間を再照会せず、その日付に従ってください。日付は、--rank-type に応じた鮮度ウィンドウ内である必要があります。 day は過去30日以内、week は過去6か月以内、month は過去12か月以内（いずれも 今日 から遡って）です。古すぎる日付（例：昨年）は、上流で rant_type N only support … として拒否されます。その場合は、rank-type を切り替えずに、日付を今日に近づけてください。
• カテゴリーフィルターは数値で指定し、階層ごとに分かれています。 rank／list の対象カテゴリーを絞り込むには、まず category resolve --keyword <term> を実行します（例：lipstick／口红。CJK のキーワードでは zh ツリーが自動的に使われます）。各一致項目の階層と祖先 ID {l1_id, l2_id?, l3_id?} が返されます（ID はどの地域でも使えます）。対象コマンドが受け取る階層の ID を渡してください。 product／seller の rank／list では、L1→--category-id、L2→--category-l2-id、 L3→--category-l3-id を使います（--category-id は L1 専用です。L2／L3 の ID を指定しないでください）。 指定する階層は、1つの親子関係の連鎖を構成する必要があります。同じ ID の重複や不一致があると、ローカルで拒否されます（費用はかかりません）。問題のフィールドは issues に、正しい ID は suggested に記載されるので、それをコピーして再送してください。issues の各項目には、field、reason、value、ローカライズされた message、構造化された detail（同じ内容の機械可読形式）が含まれます。コードで分岐する場合は detail、人に表示する場合は message を優先してください。次に、 creator の rank では任意の階層を --product-category-id で指定できます。video の rank が受け付けるのは L1（l1_id）のみです。L2／L3 の ID を指定すると、L1 の祖先に自動的に引き上げられ、フィルター範囲が広がります（レスポンスの category_level_corrected にその旨が示されます）。信頼度の低い hint が返された場合は、category tree（L1＋L2 の概要）を実行し、意味に基づいて分岐を選んでから、category tree --parent <that L2 id> を実行して L3 の末端まで確認してください。ランキングを使わない通常のキーワード検索では、find products --keyword に ID は不要です。
• find products が返すのは product_id のみです（これは検索インデックスです）。タイトル／価格／指標を取得するには、その ID を product detail に渡してください。
• 空の []／null はエラーではなく、「該当なし」を意味します。 同じ空のクエリを繰り返すと、cached: true と retry_after（ISO タイムスタンプ）が返される場合があります。バックエンドはそのフィルターにデータがないことを記録し、指定時刻の後に自動で再調査します。ポーリングせず、フィルターを変更するか、次に進んでください。データが少ない、または挙動に注意が必要な項目： creator region（信頼性が低いため、代わりに creator profile の region を参照してください）、 video captions（字幕のない動画が多数あります）、live detail（ライブ配信中のルームのみ）、seller inventory（ショップが現在商品を掲載していない場合は空です。履歴を確認するには seller catalog を使ってください）。
• レスポンスは要点に絞ってサーバー側で整形されています（ID、主要指標、名前、主要リンク。画像はすでにアクセス可能な URL に変換済みです）。生の blob を処理する必要はありません。
• すべての金額は USD です。 価格／平均価格／GMV のすべてのフィールド（min_price、 max_price、spu_avg_price、*_gmv_*_amt など）は、--region に関係なく USD に換算された数値です。レスポンスの "currency": "USD" でも確認できます。¥／円 のような現地通貨の記号を付けないでください。レポートで現地通貨が必要な場合（例：日本市場の調査で JPY が必要な場合）は、最新の為替レートを使って USD から換算し、概算であることを明記してください。

売れる動画のプロンプトジェネレーター — clipcat prompt search

Clipcat 独自の構造化プロンプトライブラリです。TikTok のあらゆる市場やカテゴリーから、実際に売上を生み出した動画をリバースエンジニアリングし、実際の GMV 順に並べています。これは TikTok 検索ではありません。ここに掲載されている動画はすでに分析され、そのまま動画モデルに渡せるプロンプトに書き直されています。

ユーザーが売れる動画のプロンプト、アイデア、台本、切り口を求めたら、一から作成するのではなく、まずここを確認してください。 実績のある動画をもとにしたプロンプトこそが重要です。新たに作ったものは単なる推測にすぎず、ユーザーにはその違いがわかりません。

ステップ 1 — 実績のある動画から最も近いものを探す

• prompt search --query "<what you want>" — ライブラリを対象に、意味検索とキーワード検索を行います。 「暖かみのある室内照明、手持ちカメラのクローズアップ、実際の人物がカメラに映っている」のように雰囲気を説明しても、ブランド名や ASMR、OOTD のように具体的な言葉を指定しても使えます。両方を組み合わせて検索するため、どちらの検索方法が適しているかを推測する必要はありません。任意のフィルター：--region（小文字の市場コード）、--category（TikTok Shop の L1 コード。例：beauty-personal-care）、--video-type（real-review | ootd | asmr | unboxing-pov | …）、--limit（1〜20）。 ユーザー自身の商品やオーディエンスをもとに、商品内容、対象者、市場、希望する雰囲気をクエリに含めてください。カテゴリー名だけ（「skincare」など）を指定すると、ライブラリの一般的な内容が取得されます。 ほかの読み取りコマンドとは料金体系が異なります。有料プランには無料検索枠が含まれ、枠を超えた呼び出しは 1 回につき 3 クレジットかかります（ほかの読み取りコマンドは一律 6 クレジットです）。レスポンスには quota.remaining / quota.free_quota / quota.cost_after_quota が含まれます。残りが少なくなったら、次の呼び出しでユーザーを驚かせないよう、残りを伝えてください。
• 結果を信頼する前に、weak_match と degraded を確認してください。 ライブラリは利用可能な中から最も近い項目を返すため、結果が一覧いっぱいに表示されたからといって、必ずしも検索内容に合っているとは限りません。 weak_match: true は、近いものが見つからなかったことを意味します。最も近い項目を答えとして提示するのではなく、その旨を伝え、言い換えやフィルターの削除を提案してください。 degraded: true は、意味検索を利用できず、キーワード検索のみが実行されたことを意味します。結果が不完全な可能性があり、その検索には課金されません（クォータが返還されます）。 --limit より結果が少なくても問題ありません。関連性が十分に高い項目だけが返されるため、--region と --category を絞り込んだ組み合わせで結果が少数になるのは正常です。

各検索結果には、完全な prompt テキスト（英語版は prompt_en）、元動画の指標（GMV、売上、視聴回数）、matched_facet（クエリがプロンプトのどの部分に一致したか。スタイル／カメラ／ナレーションなど）、元の TikTok 動画の source_video_url、公開ページの detail_url が含まれます。

ステップ 2 — ヒット動画をユーザー自身のプロンプトに書き換えます

ライブラリのプロンプトをそのまま返してはいけません。別の人の製品を売る内容だからです。最も適したヒット動画（または構成が一致する 2～3 本のヒット動画。構成の異なる動画を平均するとテンプレートになります）を、このユーザーの製品向けのプロンプトに書き換えます。

• 売れる要素は残します：冒頭のフックと最初の 1～2 秒に起きること、ショットの順序とテンポ、カメラ表現、照明、プレゼンターが映るかどうかとそのタイプ、ナレーションのトーン、プロモーションの仕掛け、最後の CTA。
• 製品とそのセールスポイント、画面上のテキスト、ナレーションのセリフ、市場固有の要素（言語、通貨、地域に合わせた表現）を入れ替えます。
• 裏付けできない主張は引き継がないでください。評価、販売数、受賞歴、使用前後の変化、効果に関する主張は元の製品に関するものなので、削除するか、ユーザーに自社の情報を尋ねます。
• 対象モデルに合わせます：送信する --duration の範囲内にプロンプトを収め、想定されるショット数にも合わせます（5 秒のクリップに入るのは 2 ショットであり、6 ショットではありません）。また、--lang でナレーションの言語を指定します（必須です。CLI にデフォルト値はないため、意識して選んでください）。
• クレジットを消費する前に、完成したプロンプトを、その作成元の detail_url（および source_video_url）とともにユーザーに見せます。実際の動画を引用することが、作り上げたプロンプトとの違いです。

ステップ 3 — 撮影します

• 製品画像のみの場合 → product_video を使い、書き換えたプロンプトを --prompt-file - で渡します。
• 元動画の動きやカットを参考にする場合 → ユーザーの --images を使って replicate --url <source_video_url> を実行します（TikTok のリンクではダウンロードに 10 クレジットが追加でかかります）。
• どちらも有料で、2 段階の手順が必要です：送信 → 返されたチェックリストをユーザーに提示 → 明示的な承認を待つ → --confirm <confirmId>（「2 段階の確認」を参照）。

clipcat prompt search --query "handheld close-up of a serum bottle, warm bathroom light, real user voiceover" \
  --region us --category beauty-personal-care --limit 5
# pick a hit → rewrite its prompt for the user's product → step 1 (no charge):
clipcat product_video --image serum.jpg --model seedance2 --duration 8 \
  --resolution 480p --size 9:16 --lang en --prompt-file - <<'EOF'
<the rewritten prompt>
EOF
# → confirmationRequired + confirmId. Show the checklist, wait for a yes, then:
clipcat product_video --confirm <confirmId>

動画生成とツール

使用する動画コマンド：ユーザーが別の方法を求めない限り、デフォルトではエージェントモードを使用します。製品を使ってバイラル動画を再撮影する場合は replicate、製品画像からスクリプトを作成する場合は product_video を使います。これら 2 つのコマンドでは、ユーザーは製品画像と一行の依頼を用意するだけで、スクリプト作成とストーリーボード作成を任せられます。

generate（raw）は、プロンプトとアセットをそのままモデルに送信します。AI によるスクリプト作成もストーリーボード作成も、製品ショットの合成も行いません。そのため、出力の品質は、作成するプロンプトとパラメーター次第です。フレーミング、カメラの動き、テンポ、ナレーションはすべてユーザー側で指定し、モデルがサポートする解像度、時間、アセットモードも clipcat models --raw から自分で選ぶ必要があります。ユーザーがすでに正確な指示とアセットを用意している場合、またはエージェントにアイデアを書き換えてほしくないと明示している場合に限り、この方法を選んでください。迷った場合は「説明どおりにそのまま生成しますか。それとも、エージェントにスクリプトを作成させますか？」と尋ねてください。ユーザーをデフォルトで raw モードにしてはいけません。

• generate — 動画をそのまま生成します。--prompt とアセットは、指定された内容のままモデルに渡されます。まず clipcat models --raw を実行してください。現時点でどのモデルがこの機能に対応し、それぞれが何を受け付けるかを確認できる唯一の情報源です。アセットのモードは2種類あり、フラグに応じて自動的に選択されます。参照画像（ローカルの --image ／URLまたは clipcat:// 参照の --image-url、任意の --character-id、任意の --ref-video、任意の --ref-audio）、またはフレーム（--first-frame(-url) と任意の --last-frame(-url)。キャラクター、参照動画、参照音声は指定できません）。--resolution、--duration、--size（clipcat models --raw の Ratios 列に記載されているモデルでは、9:16、16:9、または adaptive）、--enhance、--dry-run、--expected-credits も指定できます。--confirm による2段階送信を行います（下記参照）。ここでの --character-id に指定できるのは数値IDのみです（@sora 形式の名前や画像URLは指定できません）。--ref-audio に指定できるのは**clipcat:// 参照のみ**です。ローカルの音声ファイルを使う場合は、先に clipcat asset upload <file> でアップロードし、表示された ref を渡してください（ライブラリ内の音声は clipcat asset list --type audio で確認できます）。音声をまったく受け付けないモデルがほとんどです（clipcat models --raw の raw.maxAudios を確認してください）。音声のみでは送信できません（参照画像または動画と組み合わせてください）。また、長さはサーバー側で計測されるため、追加後に --dry-run で再見積もりしてください。参照ファイルと参照Webリンクは、引き続きWeb版でのみ利用できます。これらを指定するフラグはありません。
• models --raw — そのまま生成する際の機能表です。モデルごとの画像モード、画像数の範囲、フレームスロット、参照動画の上限、プロンプトの上限、キャラクター対応状況、Ratios 列（そのモデルが対応するアスペクト比。adaptive は対応モデルにのみ表示されます）、さらに組み合わせごとの最新クレジット料金を確認できます。RefVideo 列に +output ≤Ns と表示されるモデルでは、その上限秒数を参照動画と --duration で共有します。上限を超えると送信は拒否されます。これらの上限は、その時点で有効なプロバイダーによって変わります。必ず表を確認し、決めつけないでください。 このアカウントでそのまま生成する機能が有効でないと表示された場合は、代わりに replicate ／ product_video を使用してください。
• quote — 特定の生成1件にかかる正確なクレジット数を返します（--model ＋ --resolution ＋ --duration。TikTok／Douyinの再現では --url ／ --social を、超解像では --enhance も指定します）。任意の料金プレビューであり、確認手順ではありません。サーバーが計算をすべて行い、totalCredits（超解像の料金を含む）と enhanceCredits ／ enhanceBlocked を返します。モデルの比較や --expected-credits への入力に便利です。ユーザーに実際に提示する確認事項は、送信処理自体から取得します（「2段階確認」と「超解像」を参照）。
• models — 利用可能なすべての動画モデルとそのクレジット料金（離散値は prices、範囲は creditsPerSecond）、画像モデルと画像1枚あたりのクレジット料金（imageModels）、および残高を確認できます。ユーザーがまだモデルを選んでいない場合や、利用できないモデルが報告された場合に使用してください。一覧は最新の状態で、現在プロバイダーがあるティアのみが含まれます。resolutions ／ prices にない解像度や長さでの送信は拒否されるため、ここに表示されていない組み合わせで送信しないでください。
• replicate — 商品画像を使ってバズ動画を再現します。参照動画には --url（TikTok／Douyinリンク、直接URL、または以前のアップロードで取得した clipcat:// 参照。種類は自動判定）または --video（ローカル動画ファイル。最大100MB。署名付きURLでアップロード後、サーバー側で縮小されます。同じファイルを再度使う場合はアップロードを再利用し、ダウンロードの追加料金はかかりません）のどちらか一方のみを指定します。商品画像には --image（ローカル）または --image-url（URL）を指定します。ローカルファイルとURLは混在させられます。--model、--duration、--size（9:16 または 16:9 のみ）、--lang（必須。デフォルト値なし）、--resolution、--enhance（超解像。下記参照）、--character-id、--expected-credits に対応しています。--confirm による2段階送信を行います（下記参照）。
• product_video — 参照動画を使わず、商品画像のみから動画を生成します。画像には --image（ローカル）または --image-url（URL）を指定します。ローカルファイルとURLは混在させられます。--size に指定できるのは 9:16 または 16:9 のみです。--lang は必須です（デフォルト値なし。動画の音声／字幕の言語なので、ユーザーに確認してください）。--enhance（超解像。下記参照）、--expected-credits に対応しています。--confirm による2段階送信を行います（下記参照）。
• image — GPT Image モデルを使い、テキストプロンプトからAI画像を生成します。任意で --image（ローカルファイル）または --image-url（URL）により、最大5枚の参照画像を指定できます。--aspect-ratio で 1:1（デフォルト）／ 16:9 ／ 9:16 を選択します。サイズ指定（9:16／16:9／1:1、縦長／横長／正方形、バナー、壁紙）は、--prompt と --aspect-ratio の両方に含める必要があります。--aspect-ratio はキャンバスを設定し、プロンプト内の指定は構図の基準になります。ユーザーが求めていないサイズを勝手に作らないでください。--model で画像モデルを選択します：gptimage2 | gptimage25flare（GPT Image 2.5 Flare）| gptimage25sunburst（GPT Image 2.5 Sunburst）| nanobana2（Nano Banana Pro）。画像1枚あたりのクレジット数はサーバー設定によるため、clipcat models の imageModels セクションで確認してください。ユーザーが特定のモデルを指定していない限り、--model を指定しないでください（省略した場合はサーバーのデフォルトが使われます。これはサーバー側で設定され、必ずしも gptimage2 とは限りません）。また、送信前に画像1枚あたりのクレジット数をユーザーに伝えてください。
• list_images — サーバーの画像生成タスクを一覧表示します。--status ／ --limit ／ --page で絞り込めるほか、--scope all ／ --scope <member-user-id> に対応しています（オーナー／管理者のみ。creatorName が追加されます）。
• breakdown — 動画を分析します（台本、シーン、音楽）。以前に分析済みの場合は、キャッシュされた結果をすぐに返します。
• download — TikTok／Douyin動画をダウンロードします（署名付きURLを返します）。キャッシュされた結果はすぐに返されます。
• query_task — IDと種類を指定してタスクの状態を確認します（--type replicate | product | raw | breakdown | download | image）。ローカルの最新タスクを再開する場合は --task-id を省略します。--enhance を指定すると、各 videos[] アイテムに独自の status ／ enhanceStatus が含まれます（「超解像」を参照）。ワークスペースのオーナー／管理者は、メンバーのタスクも確認できます。
• list_tasks — サーバーの最近の動画関連タスクを一覧表示します（--type は必須：replicate | product | raw | breakdown | download）。画像タスクには list_images を使用してください。--scope all ／ --scope <member-user-id> を指定するとワークスペース全体に範囲が広がります（オーナー／管理者のみ。creatorName が追加されます）。デフォルトでは自分のタスクのみが対象です。
  • 各行には異なるIDが2つあります。 taskId はプロジェクトID（/project/<id> のリンクに含まれるID）です。完了した動画はそれぞれ独自の videos[].videoTaskId を持ちます。1つのプロジェクトに複数の動画（スクリプトごとに1本）を含められるため、これらのIDが一致することはありません。1本の動画に対する操作（特に上記の tiktok publish --video-task-id）では、taskId ではなく必ず videoTaskId を指定してください。query_task も同じ2つのIDを返します。
• character list — アカウントに保存されているキャラクターを一覧表示します（id、name、status、type）。id は replicate ／ product_video ／ generate の --character-id に指定する値です。使用できるのは status: completed のキャラクターのみです。--status ／ --limit ／ --page ／ --sort-by ／ --sort-order に対応し、--scope all ／ --scope <member-user-id> も指定できます（オーナー／管理者のみ。creatorName が追加されます）。無料です（アカウントメタデータのみ。クレジットは消費しません）。
• asset upload <file> — ローカルの画像（jpg/png/webp、≤10 MB）、動画（mp4/mov、≤150 MB）、または音声（mp3/wav/m4a/aac、≤10 MB）を、Webサイトと同じ方法でアセットライブラリにアップロードし、clipcat:// 参照を表示します（音声／動画はサーバーが計測した長さも表示します）。画像の ref はそのまま --image-url ／ --first-frame-url に、mp3/wav音声の ref は --ref-audio に渡してください（m4a/aacもアップロードできますが、--ref-audio では拒否されるため、先に変換してください）。動画はライブラリに保存されますが、generate --ref-video にはローカルファイル自体を渡してください。--name で表示名を設定できます。無料です（ストレージの容量を使いますが、クレジットは消費しません）。
• asset list — アカウントに保存されているアセット（type、name、長さ、サイズ）と、それぞれの clipcat:// 参照を一覧表示します。この参照を --image-url ／ --first-frame-url ／ --ref-audio に渡します。--ref-video に渡せるのは clipcat://analyse/video/ で始まる場合のみです（clipcat://assets/ の動画は拒否されるため、代わりにローカルファイルを渡してください）。参照は1文字ずつ正確にコピーし、再入力したり組み立て直したりしないでください。Webサイトからユーザーがアップロードしたファイルの参照を確認するには、このコマンドを使用します。--type image|video|audio|document ／ --q <name> ／ --limit ／ --page に対応し、--scope all ／ --scope <member-user-id> も指定できます（オーナー／管理者のみ。creatorName が追加されます）。無料です（アカウントメタデータのみ。クレジットは消費しません）。

TikTok への投稿 — clipcat tiktok

名詞・動詞形式：clipcat tiktok <connect|connect-status|accounts|creator-info|publish|tasks|task|cancel>。 投稿にクレジットはかかりません。上限は接続済みアカウント数です（無料：0／basic：3／creator+：無制限）。 透かしのないレンダリングのみ投稿できます（TikTok は、API クライアントがクリエイターのコンテンツに透かしを入れることを禁止しています）。透かし入りの動画は、送信時に watermarked_video エラーで拒否されます。

• connect — 初回のみ必要な認証です。同意ページがブラウザーで開きます。GUI がない環境（SSH／コンテナー）では、リンクが標準エラー出力に表示されるため、--json の解析には影響しません。コールバックはこのマシンではなくサーバーに届くため、スマートフォンでページを開いてもかまいません。connect-status --state <state> でポーリングします。ユーザーがキャンセルすると denied と表示されるため、そのまま待たないでください。
• accounts — 接続済みアカウントとその openId を表示します。他のすべてのサブコマンドでは --open-id を指定します。
• creator-info — 直接投稿の前に毎回実行してください。 アカウントで受け付け可能な --privacy 値を判断する唯一の基準は privacyLevelOptions です（非公開アカウントで選択できるのは SELF_ONLY のみです）。maxVideoPostDurationSec と、アカウントでコメント／デュエット／スティッチが無効になっているかどうかも表示します。プライバシーレベルが拒否された場合は、同じ値を再試行せず、ここで選択肢を確認してください。
• publish — 有料動画コマンドと同様の2段階方式です（「2段階確認」を参照）。ただし理由は異なります。クレジットは消費しませんが、ユーザーの公開 TikTok アカウントにコンテンツを投稿する唯一のコマンドであり、投稿が公開されると、ここから取り消すことはできません。最初の呼び出しでは入力を検証し、投稿するすべての内容（アカウント、動画、投稿モード、キャプション、閲覧できるユーザー、コメント／デュエット／スティッチ、AIGC とブランドコンテンツの開示、スケジュール）のチェックリストと confirmId を返します。動画ソースは次のいずれか1つだけ指定してください：--video-task-id（完成済みの Clipcat 動画。list_tasks／query_task の videos[].videoTaskId を指定します。プロジェクトレベルの taskId ではありません。プロジェクト ID を渡すと errorCode=video_task_is_project_id で失敗し、エラーに正しい ID が表示されます）、--asset-id（アセットライブラリ）、または --video <path>（ローカルファイル。先にアップロードされ、ストレージクォータに算入されます）。
  • --mode direct（デフォルト）はすぐに投稿し、--privacy の指定が必須です。--mode draft は動画のみを TikTok の下書き受信箱に送ります。この場合、--title、--privacy、--allow-*、--brand-*、--aigc、--cover-ts-ms は無視され、ユーザーは TikTok アプリ内でそれらを入力します。
  • インタラクション用フラグ（--allow-comment／--allow-duet／--allow-stitch）は、TikTok の UX ガイドラインに従い、デフォルトではオフです。アカウントで無効になっている場合、サーバーが強制的にオフにします。
  • --brand-content（有料パートナーシップ）は SELF_ONLY と併用できません。
  • --schedule は後で投稿するよう予約します（直接投稿のみ、5分後から30日後まで）。タイムゾーンオフセットの指定は必須です。2027-03-01T20:00:00+08:00 は北京時間の20:00（UTC+8）、2027-03-01T12:00:00Z は同じ時刻を UTC で表したものです。オフセットのない 2027-03-01T20:00:00 は拒否されます。ほとんどのユーザーは自分のタイムゾーンでの時刻を指定するため、頭の中で Z に変換せず、ユーザーのタイムゾーンオフセットを付けてください。ここでは --wait は無視されます。タスクは SCHEDULED として返され、cancel --task-id <id> で取り消せます。
  • 生成コマンドと同様に非同期です。アップロードはサーバー側で実行され、タスクが作成されるとコマンドはすぐに戻ります。--wait を指定すると15秒ごとにポーリングして待機するため、ツール呼び出しのタイムアウトを避けるには、送信後に別のターンで task --task-id <id> を使う方法がおすすめです。
• tasks／task --task-id <id>／cancel --task-id <id> — 投稿タスクを一覧表示する、1件のタスクを確認する、または予約済みのタスクを取り消します。

スケジュールタスク — clipcat schedule

名詞・動詞形式：clipcat schedule <list|show|create|update|enable|disable|delete|run>。 スケジュールは保存されたプロンプトで、Clipcat Agent が --timezone（IANA 形式。例：Asia/Shanghai）の --at（24 時間表記の HH:mm）に、毎日、または --days（mon,wed,fri／weekdays／weekends）に従って自動実行します。実行のたびにウェブサイト上に新しいチャットが作成され、メールも送信されます（--notify none で無効化できます）。

• 費用：管理は無料です。スケジュールによる実行も run による実行も、通常の Agent チャットターンと同じ料金が発生し、確認なしで最大 3 件の生成タスクを送信する場合があります。有料プランでのみ利用できます。1 アカウントにつき最大 100 件まで登録できます（無効なスケジュールも件数に含まれます）。
• create には --title、--prompt（または --prompt-file -）、--at、--timezone が必要です。ユーザーにタイムゾーンを尋ね、決して推測しないでください。この実行ではこの会話の内容を記憶していないため、プロンプトは単独で完結した指示として記述し、clipcat:// の参照はそのまま貼り付けてください。作成する前に、プロンプト、時刻、曜日、タイムゾーンをユーザーに確認してください。
• update --id は、指定したフラグだけを変更します。--at または --days の片方だけを指定した場合は、もう片方をそのまま維持します（--days daily は毎日を意味します）。スケジュールの有効化・無効化は行いません。enable／disable を使ってください。
• Agent モードのみ対応しています。ウェブサイトで作成したワンクリック生成／動画生成スケジュールはここには表示されず、not_found が返されます。
• delete は取り消せず、run はすぐにクレジットを消費するため、事前に明確な承諾を得てください。run はすぐに結果を返します。その後、show --id で lastStatus と lastResultUrl を確認してください。schedule_running は実行中のタスクがすでにあることを示します。ループして再試行しないでください。
• nextRunAt／lastRunAt は UTC です。

テキスト読み上げ — clipcat tts

スクリプトを、プリセット音声またはクローン音声によるナレーション入り MP3 に変換します。同期処理で、所要時間は約 2～10 秒です。MP3 はアセットライブラリに保存されます。返される ref（clipcat://…）は、clipcat generate --ref-audio の参照音声としてそのまま使えます。

• 費用：100 文字あたり約 5 クレジット（最低 1 クレジット）。モデルにかかわらず料金は同じで、成功した場合のみ課金されます。音声のクローン作成は無料です。料金を確認し、音声を合成する前にユーザーへ伝えてください。料金の確認には --dry-run／tts voices の結果を使用してください。
• モデル（--model、通常は省略）：デフォルトの seed-tts-2.0 はプリセット音声のみ対応し、単語単位のタイムスタンプを返す唯一のモデルです。クローン音声には cosyvoice-v3.5-plus（デフォルト）または fish-s2.1-pro が必要です。モデルが対応していないフラグを指定すると、課金されずにエラーになります。
• tts voices [--language en] [--model M] — モデル（プリセット／クローン／対応フラグ／利用可否）、推奨音声 ID、--language の値、料金を確認できます。無料です。リストにない音声 ID は、--model が指定されていない限り seed-tts-2.0 に割り当てられます。
• tts --voice <id|clone_<id>> --text "…"（長文または引用符で囲んだテキストには、--text-file - <<'EOF' … EOF を使用します）。1 回の呼び出しで最大 1000 文字です。これを超えるスクリプトは、文またはシーンごとに分割してください。任意で --language（テキストは指定した言語で記述する必要があります。seed-tts-2.0 と en／zh-cn の組み合わせでは words のタイムスタンプも返されます）、--instruction（トーン。文字数分も課金されます）、--speed／--volume（-50～100、0 = 標準）を指定できます。
• --out <file> を指定すると、MP3 もローカルに保存されます（--force を指定しない限り、既存ファイルは上書きされません）。保存に失敗しても音声の生成料金は発生し、ライブラリにも保存されています。再実行せず、ref／audioUrl を再利用してください。
• tts clone --audio <local file | clipcat://ref> [--start S] [--duration D] [--name N] [--transcript T] [--dry-run] — 無料で、voice: clone_<id> が返されます。サンプルは 10～60 秒で、話者は 1 人、明瞭な音声である必要があります。音声または動画に対応しています（mp3 wav m4a aac ogg flac mp4 mov webm、≤20MB。音声トラックが抽出されます）。これより大きな動画の場合は clipcat asset upload <file>（≤150MB）を使い、表示された clipcat:// 参照を渡してください。すでにライブラリにある場合は clipcat asset list --type audio|video を使います。それ以外の URL は、先にダウンロードしてください。ユーザーが使用権を持つ音声のみをクローンしてください。
• tts clones [--q NAME] [--page N] [--limit N] [--scope mine|all|<userId>] — ユーザーのクローン音声を一覧表示します。無料です。

プロンプトの渡し方（シェルに加工させないでください）

エスケープが誤っている --prompt \"Create a 5s video\" は、CLI に "Create として渡され、最初の空白で切り詰められます。CLI とサーバーは現在、このような入力を受け付けず、無意味な動画への課金を防ぎます。ただし、そもそもこれが起きないようにプロンプトを渡してください。

• プロンプトに引用符、改行、$、またはバッククォートが含まれる場合は、インラインフラグではなく標準入力を使います。

  clipcat product_video --image-url <url> --model seedance2 --duration 5 \
    --expected-credits 100 --prompt-file - <<'EOF'
  Create a 5-second UGC demo. The narrator says "this changed my routine".
  EOF
  

  引用符付きの区切り文字 <<'EOF' は、あらゆる種類の展開を無効にします。エスケープは一切不要です。 bash、zsh、Git Bash で動作します。Windows PowerShell ではパイプを使わず、UTF-8 ファイルを書き込み、そのパスを渡してください。

  Set-Content -Encoding utf8 prompt.txt @'
  Create a 5-second UGC demo. The narrator says "this changed my routine".
  '@
  clipcat product_video --image-url <url> --prompt-file prompt.txt
  

  Windows でパイプを使わない理由：Windows PowerShell 5.1 は、パイプ出力をネイティブプログラムに渡す際に $OutputEncoding でエンコードします。これはデフォルトで ASCII です。そのため、中国語などの非 ASCII 文字は すべて黙って ? に置き換えられ、???????? というプロンプトも引用符のチェックでは完全に正しいように見えます。 どうしてもパイプを使う必要がある場合は、先に $OutputEncoding = [System.Text.Encoding]::UTF8 を実行してください。（PowerShell 7 はどこでも UTF-8 がデフォルトなので影響を受けませんが、上記のファイルを使う方法はどちらでも動作するため、その方法を使ってください。）また、@' は行末に置き、'@ は単独の行の先頭に置く必要があります。1 行にまとめた @' … '@ は構文エラーになります。5.1 では、Out-File は Set-Content -Encoding utf8 の代わりにはなりません。デフォルトのエンコードが UTF-16 のため、CLI に拒否されます。

• ファイルの内容を文字列に読み込んでインラインで渡すことは避けてください。--prompt (Get-Content p.txt) のような方法は使わないでください。 PowerShell 5.1 では、Get-Content は UTF-8 ファイルを ANSI としてデコードするため、引用符の異常がない有効な UTF-8 の文字化けが発生します。すべてのチェックを通過した結果、無意味な動画に課金されてしまいます。ファイルのパス（--prompt-file p.txt）を渡し、CLI にバイト列を読み取らせてください。

• 短い 1 行のプロンプトは、--prompt "…" のようにインラインで渡してもかまいません。外側の引用符をバックスラッシュでエスケープしたり、すでに引用符で囲まれた文字列をさらに引用符で囲んだりしないでください。

• --prompt と --prompt-file は同時に指定できません（- は標準入力、それ以外はファイルパスです）。

• 送信後、CLI は Prompt sent (N chars): … と表示します。意図した内容と一致しているか確認してください。N が違う場合は、書いたプロンプトではなくコマンドラインが加工されています。

• 引用符が誤ったプロンプトのために送信を拒否された場合、同じコマンドを再試行しないでください。--prompt-file - を使って再送信してください。拒否は課金前に発生します。

2段階確認

次の4つのコマンドは2回の呼び出しで実行し、同じターンで両方を実行してはいけません。 クレジットを消費するreplicate、product_video、generateと、ユーザー自身の公開アカウントに投稿され、取り消せないtiktok publishです。クレジットを自分で計算してはいけません。サーバーから返される値を使用してください。

ステップ1 — 通常どおり送信します。 いつもどおり、コマンド全体を実行してください。サーバーはすべてを検証しますが、課金もタスクの作成も行いません。代わりに、confirmIdと確認用のスナップショット（generationType、model、resolution、duration、size、lang、imageCount、プロンプト全文、およびクレジットの内訳credits／downloadSurcharge／enhanceCredits／totalCredits）を含むdata.confirmationRequired: trueと、instruction文字列を返します。終了コードは0です。これはエラーではないため、再試行したりパラメーターを変更したりしないでください。

ステップ2 — チェックリストをユーザーに提示して、そこで停止します。 パラメーター、プロンプト全文、totalCreditsを表示し、instructionをそのまま出力して、会話内でユーザーから明示的な返答があるまで待ちます。沈黙、「よさそうです」という返答、またはあなた自身の判断は承認ではありません。ステップ3を同じターンに続けて実行してはいけません。

ステップ3 — 明示的な承認を得た後にのみ実行します。

clipcat product_video --confirm cfm_7QK2M8   # or clipcat replicate / clipcat generate --confirm ...

--confirmとビジネスパラメーターは併用できません。サーバーはステップ1で保存したスナップショットを送信するため、パラメーターを渡しても何も反映されず、誤解を招くことがないようCLIはその組み合わせをローカルで拒否します。--output、--api-key、--base-url、--poll、およびtiktok publishの--wait／--timeoutといった接続用フラグは使用できます。パラメーターを変更する場合は、変更後の値でステップ1に戻り、新しいチェックリストの承認を得てください。

完全な例（Seedance 2、デフォルトの480p、8秒、TikTokリンク）：

clipcat replicate --url "https://www.tiktok.com/@u/video/123" \
  --image product.jpg --model seedance2 --duration 8 --resolution 480p \
  --size 9:16 --lang en
# → confirmationRequired, confirmId cfm_7QK2M8, total 170 credits (160 + 10 download)
# → show the checklist, wait for the user's yes, then:
clipcat replicate --confirm cfm_7QK2M8

tiktok publish — 同じプロトコル、異なるチェックリスト

3 つのステップは同じです。異なるのは、ユーザーに承認を求める内容です。 data.confirmationType は tiktok_publish です（2 つの生成コマンドでは video です）。また、confirmation スナップショットには、アカウント、動画（ソース、タイトル、長さ）、投稿モード、キャプション、プライバシーレベル、コメント／デュエット／スティッチ、AIGC およびブランドオーガニック／ブランドコンテンツの開示フラグ、スケジュール、カバー画像に加え、サーバーが計算した次の 2 つのリストが含まれます。

• forcedOff — ユーザーが有効にするよう指定したものの、このアカウントの TikTok 設定で無効になっているインタラクションです。オフの状態で投稿されます。その旨を伝えてください。再試行しないでください。
• ignoredInDraft — 渡されたものの、--mode draft では送信されない設定です（TikTok ではアプリから設定します）。指定した値は適用されません。

clipcat tiktok publish --open-id _000abc... --video-task-id 4211 \
  --privacy PUBLIC_TO_EVERYONE --title "New drop" --allow-comment
# → confirmationRequired, confirmId cfm_7QK2M8, plus the full post checklist
# → show it, say plainly that this posts to their public account, wait for a yes:
clipcat tiktok publish --confirm cfm_7QK2M8

確認が成功すると taskId が返されます。taskId がなければ何も公開されていません。投稿としてではなく、必ず失敗として報告してください。1.0.43 より古い CLI では公開できません。サーバーは明示的な「clipcat update を実行してください」というメッセージで拒否します。これは、そのバージョンでは確認チェックリストを作成済みのタスクとして読み取り、存在しない公開タスクを表示するためです。ステップ 1 の前に creator-info を実行する価値はあります。アカウントが受け付ける --privacy の値を確認できる唯一の手段であり、--video に大きなローカルファイルを指定した場合にアップロードが拒否されるのを防げます。

確認とは別に使える追加機能：

• clipcat quote はステップ 1 の前に費用をプレビューします（パラメーターは同じです。ダウンロード料金を含めるには --url、超解像を含めるには --enhance を追加します）。ユーザーとモデルを比較する際に便利です。クレジットを自分で計算しないでください。quote またはステップ 1 のチェックリストで返される値を使用してください。Raw 生成には代わりに clipcat generate --dry-run を使用します（quote では Raw の料金は確認できません）。
• Raw の --dry-run はアセットもアップロードし、clipcat:// 参照を返します。再アップロードを省略するには、これらをステップ 1 に渡してください。これは確認ステップではなく、confirmId も返しません。
• ステップ 1 の --expected-credits <n> では費用に上限を設けられます。実際の費用が上回る場合にのみサーバーがリクエストを拒否します（実際の費用が安い場合、たとえばキャッシュヒットやプロモーションの場合は、そのまま処理されます）。拒否された場合は現在の費用が返されます。再確認して再送信してください。

ユーザーがまだモデルを選んでいない場合（またはすべてのモデルを確認する必要がある場合）は、clipcat models を実行すると、利用可能な全モデルとその費用が表示されます。

プレミアムモデル（例：seedance2、happyhorse10）には有料プランが必要です。clipcat quote はこれらに premiumBlocked のフラグを付け、サーバーは無料ユーザーによる使用を拒否します。

Raw 生成（generate）では quote ではなく --dry-run で見積もります

clipcat quote では generate の料金を確認できません。代わりに、送信する予定のコマンドをそのまま組み立て、--dry-run を追加してください。すべてを検証し、アセットをアップロードまたは解決して、送信時に課金されるものと同じ totalCredits を返します（見積もりと課金では同じサーバー側の計算が使われるため、差異は生じません）。タスクは作成されず、クレジットも消費されません。レスポンスには、アップロードされたすべてのアセットの clipcat:// 参照も含まれます。実際に送信する際に再利用すれば、二重にアップロードされません。

clipcat models --raw
clipcat generate --model seedance2 --resolution 720p --duration 10 \
  --prompt "A cat drinking coffee, cinematic" --image ./cat.jpg --dry-run
# → TOTAL: 410 credits ... image ref: clipcat://<key>
# confirm 410 credits with the user, then submit the same command with the ref:
clipcat generate --model seedance2 --resolution 720p --duration 10 \
  --prompt "A cat drinking coffee, cinematic" --image-url clipcat://<key> \
  --expected-credits 410

プロンプトで特定のアセットを指定する

モデルによっては、プロンプト内で位置を指定して個々のアセットを指し示せます。clipcat models --raw は、モデルごとにこの指定方法を raw.mention として表示します。

"mention": { "dialect": "at_en", "kinds": ["image", "video", "audio"],
             "examples": { "image": "@image1", "video": "@video1", "audio": "@audio1" } }

• すべてのモデルで指定方法は同じです：@image1 / @video1 / @audio1。 これだけを書き、それ以外は何も追加しないでください。サーバーは送信時に、上流モデルが求める形式（@图片1、图1、[Image 1]、<IMAGE_REF_0> …）に変換するため、あるモデル向けに書いたプロンプトは、ほかのモデルでもそのまま使えます。
• kinds はモデルごとに異なります。これは、そのモデルで指定できるアセットの種類を示します（Grok の上流モデルが指定できるのは画像のみで、Omni は音声を指定できません）。kinds にない種類を記載しても、通常のテキストとして扱われます。
• 大文字と小文字は区別されません（@Image1 も使えます）が、小文字の形式を使用してください。
• 番号は種類ごとに、1から始まり、アセットを渡す順に割り当てられます。ローカルファイルと clipcat:// 参照は、混在していても、記述した順序が維持されます。キャラクター画像（--character）は、最後の参照画像として数えられます。
• 同じアセットを2回渡すと拒否されます（media_duplicate）。上流モデルが重複を除外し、その後の参照番号がすべて1つずつずれてしまうためです。
• これは自然言語によるソフトなヒントであり、検証は行われません。添付していないアセットを参照すると、通常のテキストとして扱われますが、クレジットは消費されます。
• mention フィールドがないモデルでは、アセットを指定できません。上流モデルが指定方法を公開していないためです。そのモデル向けのプロンプトでは、アセットに言及しないでください。
• メンションは変換後にプロンプトを長くします（@image1 → <IMAGE_REF_0>）。長さ制限は変換後のテキストに適用されます。--dry-run には実際の長さが表示されるため、自分で数えた文字数よりもこちらを優先してください。
• 参照フレーム（--first-frame / --last-frame）は番号ではなく役割に紐付けられているため、メンションできません。

参照動画（--ref-video）はアップロードされ、長さはサーバー上で計測されます。一部のモデルでは、その長さによって料金が変わるため（モデル行の repricedByReferenceVideo を確認してください）、参照動画を追加または変更した後は必ず --dry-run を再実行し、新しい合計金額を確認してください。

参照音声（--ref-audio）に指定できるのは clipcat:// 参照のみです。clipcat asset upload <file> でローカルファイルをアップロードする（参照先が表示されます）か、clipcat asset list --type audio から選択してください。長さもサーバー上で計測され、一部のモデルでは料金にも反映されます。追加後は --dry-run を再実行してください。音声だけでは使用できません。少なくとも1つの参照画像または参照動画と組み合わせてください。

クリップごとの長さ制限はモデルごとに異なり、全体共通ではありません。 clipcat models --raw の各モデル行には maxClipSec があり、単一の参照クリップの最長時間を示します（Seedance 2.5 は30秒、ほかのすべてのモデルは15秒）。これは、すべてのクリップの合計時間を制限する maxVideoTotalSec とは別の値です。トップレベルの clipRules.maxClipSec は、全モデルの値のうち最大のものを示すだけです（現在は30）。モデルを選ぶ前に行われるアップロード処理で使われるための値であり、これを使って検証してはいけません。この値に基づくと、Seedance 2.0 のモデルが送信時に拒否する20秒のクリップも通過してしまいます。モデル行の値を確認してください。

超解像（--enhance）

replicate、product_video、generate では、完成した動画をアップスケールするために --enhance 720p|1080p|2k を指定できます。ルールは次のとおりです。

• replicate／product_video では、生成解像度より厳密に高いティアを指定する必要があります。480p → 720p／1080p／2k、720p → 1080p／2k、1080p → 2k、2k → 選択肢なしです。（generate では有効な出力ティアであれば指定できます。生成解像度との比較は行いません。ただし、低いティアへのアップスケールにもクレジットがかかるため、より高いティアを選んでください。）CLI は値が列挙型に含まれるかどうかだけを確認し、ティアの順序はサーバーが適用します。
• 有料プラン限定です。 無料ユーザーは送信時に拒否されます。clipcat quote --enhance では enhanceBlocked: true と表示されます（アップグレードが必要です）。
• 料金 = ceil(duration_sec / 10) × ティアごとの料金（720p＝10、1080p＝20、2k＝10 秒あたり 30 クレジット）。料金は後払いで、ベース動画が成功した後にのみ課金されます。quote は料金を enhanceCredits として返し、これは totalCredits にすでに含まれています。この totalCredits を --expected-credits に指定して送信してください。generate では、同じ値が --dry-run から enhanceCredits として返され、こちらも totalCredits にすでに含まれています。
• ステータスの意味（query_task）：ベース動画の準備ができると、videos[] に status: enhancing として表示され、使用可能な videoUrl（元の動画）が含まれます。ただし、タスクが最終的な完了状態になるのは、超解像処理の完了後です（標準的な 1 分の動画では、さらに約 6～10 分かかります）。enhanceStatus: failed の場合もタスクは完了し、元の動画が納品され、超解像の料金は返金されます。

clipcat quote --model seedance2 --resolution 480p --duration 8 --enhance 1080p
# → seedance2 480p 8s → 160 credits  + 20 enhance (1080p) → total 180 credits
clipcat product_video --image product.jpg --model seedance2 --duration 8 \
  --resolution 480p --size 9:16 --lang en --enhance 1080p --expected-credits 180
# → confirmationRequired; show the checklist, wait for a yes, then:
clipcat product_video --confirm <confirmId>

replicate：参照動画のソース

clipcat replicate では、参照動画を --url／--video のいずれか一方だけで指定します。

• --url TikTok／Douyin のリンク → /replicate_from_social を呼び出します（ダウンロードに追加で 10 クレジットかかります）。
• --url 動画の直接 URL → /replicate を呼び出します。
• --video ローカルファイル（最大 100MB）→ 署名済み URL 経由でアップロードした後、/replicate を呼び出します（ダウンロード追加料金なし）。同じファイルを再度アップロードすると重複排除されるため（コンテンツハッシュを使用、ユーザーごと）、繰り返しの複製ではアップロードが省略されます。

ソーシャルメディアの --url を指定して実行する前に、追加の 10 クレジットがかかることを必ずユーザーに伝えてください。

clipcat:// アセット参照

以前のターンで見た clipcat://... 文字列は、安定したアセット参照です。--image-url／--first-frame-url／--last-frame-url／--ref-video／--ref-audio／--character-id／replicate --url の各フラグには、そのまま渡してください。https:// を先頭に追加したり、変更したりしないでください。サーバーが署名済み URL に解決します。入力を間違えた参照は最初の段階で拒否され（クレジットは課金されません）、メモリーから再入力しないでください。詳細はサブコマンドの -h を参照してください。

参照をまだお持ちでない場合は、clipcat asset upload <file> でローカルの画像／動画／音声ファイルをアップロードすると、その参照が表示されます。clipcat asset list では、ウェブサイトでユーザーがアップロードしたものも含め、アカウントにあるすべてのアセットの参照が表示されます（音声の場合は --type audio）。

--character-id は replicate／product_video では次の 3 つの形式を使用できます。clipcat character list に表示される数値 ID（ID を推測しないでください）、@<sora-username>、画像 URL／clipcat:// 参照です。generate で受け付けられるのは数値 ID のみです。

非同期タスクのルール

replicate、product_video、generate、image、breakdown は非同期です。いずれもタスク ID を返してすぐに終了し、処理をブロックすることはありません。

一般的な所要時間は、image が約3分、breakdown が数分、product_video／replicate／generate が10分以上です。1回のツール呼び出し内で同期的に完了を待とうとしないでください。現実的なエージェントハーネスにはすべてツール呼び出しのタイムアウト（通常60秒）があり、タスクが完了するずっと前に呼び出しが終了してしまいます。常に、送信 → 戻る → ターンをまたいでポーリング、の順に進めてください。

1. タスク ID は自動的に ~/.clipcat/tasks.json にローカル保存されます。
2. clipcat query_task --task-id <id> --type <type> でステータスを確認します。各呼び出しは現在のステータスを返してすぐに終了します。最新のタスクを再開するには --task-id を省略します。status が completed または failed になるまで、ターンをまたいでコマンドを再実行してください（推奨間隔：image は約30秒、breakdown／product_video／replicate は約1～2分）。
3. clipcat list_tasks --type <replicate|product|raw|breakdown|download> を使うと、サーバー上で指定したタイプのタスクを確認できます（raw は generate のタスクです）。

query_task：自動再開

フラグなしで clipcat query_task を実行すると、~/.clipcat/tasks.json から最新のタスクを自動的に読み込み、再開します。タスク ID を覚えておく必要はありません。

利用可能なモデル

トライアルモデルはすべてのユーザーが利用できます。標準モデルの利用には有料プランが必要です。

モデル ID	長さ	解像度	備考
grok_imagine	10s、15s	480p、720p	トライアル。xAI Grok Imagine 1.5、アスペクト比は9:16のみ
veo3.1fast	8s、16s、24s	720p	トライアル。Google Veo 3.1 Fast、品質とコストのバランスに優れています
omini_flash	10s、20s	720p、1080p	トライアル。Gemini Omni Flash、Googleの最新モデル
seedance2_mini	4～15s（整数を指定）	480p、720p	トライアル、プラットフォームのデフォルト（--model を省略した場合に選択されます）。Seedance 2 Mini、バリュー向けモデルです。無料プランでは480pのみ利用可能です。--resolution を省略した場合も480pになります
mmh3_promo	10s、15s	480p、720p、2K	トライアル。補助金対象のMiniMax H3チャンネルで、無料プランでも利用可能です
seedance2	4～15s（整数を指定）	480p、720p、1080p	標準（有料）。ByteDance Seedance 2、最高品質です。デフォルトは480p
seedance2_5	4～30s（整数を指定）	480p、720p	標準（有料）。ByteDance Seedance 2.5、最新世代のモデルで、最長30sのクリップに対応しています。デフォルトは480p
seedance2_fast	4～15s（整数を指定）	480p、720p	標準（有料）。ByteDance Seedance 2 Fast、高速版です。デフォルトは480p
wan30	5～30s（整数を指定）	480p、720p、1080p	標準（有料）。Alibaba Wan 3.0、最長30sのクリップに対応しています
minimax_h3	10s、15s	768p、2K	標準（有料）。MiniMax H3
happyhorse10	3～15s（整数を指定）	720p、1080p	標準（有料）。Alibaba HappyHorse 1.1

モデル一覧と、現在のモデル・組み合わせごとのクレジットコストについては、clipcat models の情報を優先してください。そこにないモデルは提供終了済みであり、-h やこの表に記載があっても、送信時に拒否されます。clipcat models に mmh3_promo が掲載されている場合は、minimax_h3 よりもそちらを優先してください。同じモデルを期間限定の補助金対象チャンネルで利用でき、必要なクレジットが大幅に少なく、無料プランでも利用できる場合があります。 clipcat generate（raw generation）では、この表は適用されません — clipcat models --raw を実行してください。Raw generation でサポートされるのは、これらのモデルの一部です。利用可能な時間の段階もより限定されており（モデルを直接呼び出し、つなぎ合わせは行いません）、各モデルが受け付ける内容 — 画像モード、画像数の範囲、フレームスロット、参照動画の上限、プロンプトの上限、キャラクターのサポート — は、その時点で有効なプロバイダーによって変わります。上限を覚えるのではなく、毎回この表を確認してください。記載されていない内容を送信すると拒否され、その時点でモデルが実際に受け付ける内容が拒否メッセージに示されます。

この表の時間の段階は各モデルが 提供する もので、clipcat models が示すのは 現在利用可能なもの です。メンテナンスのためプロバイダーが無効になることがあり、記載された段階が一時的に利用できなくなる場合があります。送信が "no available channel" というメッセージで拒否された場合、パラメーターは有効ですが、その段階には現在プロバイダーがありません。clipcat models を再実行し、最新の一覧から別の解像度／時間／モデルを選び、料金を再提示してユーザーに再確認してください。同じ組み合わせで再試行しないでください。

ユーザーが特定の段階を指定していない限り、--resolution は省略してください。 するとサーバーは、そのモデル独自のデフォルトを使用します。これはモデルの一覧に最初に記載されている解像度で、値ごろなモデル（seedance2、seedance2_5、seedance2_fast、seedance2_mini、mmh3_promo）では 480p、それ以外では 720p です。Web 版であらかじめ選択される段階と同じで、quote でも同じように解決されるため、見積もりと後からの請求にずれが生じることはありません。ユーザーが指定したものより高い段階を渡すと、ユーザーに気付かれないままクレジットが多く消費されます。

画像モデル（clipcat image --model）

以下の価格はリリース時のデフォルトです。サーバー側の設定であり、リリースなしに変更されることがあるため、この表ではなく clipcat models（imageModels）で見積もってください。

モデル ID	名前	クレジット／画像
gptimage2	GPT Image 2	20（デフォルト）
gptimage25flare	GPT Image 2.5 Flare	22
gptimage25sunburst	GPT Image 2.5 Sunburst	22
nanobana2	Nano Banana Pro	20

画像生成の料金は、モデルごと、画像ごとに発生します。ユーザーが特定のモデルを指定した場合にのみ --model を渡してください。省略すると、サーバーは gptimage2 を使用します。送信前に画像1枚あたりの料金をユーザーに伝えてください。実際に請求された額は、送信レスポンスの costCredits フィールドで確認できます。動画と同様、モデル一覧と料金の最新情報は clipcat models の imageModels セクションで確認してください。

サポートされている言語（--lang）

en zh fr de ms vi th ja ko id fil es pt ar

replicate と product_video では --lang が必須です。デフォルト値はありません。完成した動画の音声／字幕の言語を指定するため、送信前にユーザーに確認してください（モデル／時間／解像度／クレジットと併せて確認します）。この一覧にない値は、CLI とサーバーの両方で拒否されます。

リージョン（--region）

ISO 3166-1 alpha-2、大文字：US GB DE ES FR IT JP MX BR ID MY PH SG TH VN。サーバー側で検証されます。一覧にないコードを指定すると、現在許可されている一覧が返されます。

優れたエージェントの動作

• 使用するコマンドがわからない場合は、まず clipcat -h を実行してください。
• 販売用動画のプロンプト／アイデア／スクリプトを求められた場合は、まず clipcat prompt search を実行し、最も近い実績のある検索結果をユーザーの製品向けに書き換えて、その detail_url を明記してください。想像で一から作成すると、バイラルなプロンプトを生み出す唯一の要素を捨てることになります。
• 2段階のコマンド（replicate、product_video、generate、tiktok publish）では、まず1回送信してチェックリストと confirmId を取得してください（料金は発生せず、何も作成されません）。返された内容をユーザーに提示してください。生成の場合はパラメーター／プロンプト全文／totalCredits、公開の場合はアカウント／キャプション／プライバシー設定／スケジュールを提示し、会話内で明示的な承認を得てから、後のターンで --confirm <confirmId> を実行してください。自分の判断で確認を実行したり、2つの呼び出しを同じターンで連続実行したりしないでください。クレジット数を自分で計算せず、チェックリスト（または clipcat quote）から取得してください。tiktok publish の場合は、ユーザー自身の公開アカウントに投稿され、取り消せないことをはっきり伝えてください。また、確認後に taskId が返されない場合は失敗として扱い、投稿されたものとして扱わないでください。
• generate の場合は、まず clipcat models --raw を読み込んでください（制限についてはこれだけが正式な情報源です）。その後、他の有料動画コマンドと同じ2段階の手順で進めます。まず1回送信してチェックリストと confirmId を取得し、明示的な承認を得てから --confirm <confirmId> を実行してください。--dry-run は再利用可能な clipcat:// 参照も返す任意のプレビュー機能であり、確認ではありません。
• schedule create／delete／run は、実行のたびに再確認なしでクレジットを消費するため、先にユーザーの承認を得てください。
• 解像度：ユーザーが明示的に解像度の段階を指定しない限り、--resolution は省略してください。サーバーがモデルごとのデフォルト（バリューモデルでは480p、それ以外では720p）を適用し、quote も同じ方法で解決します。720p／1080pへ黙って引き上げないでください。高解像度ほど多くのクレジットが必要です。
• 重要度の高いプロンプトは、引用付きのヒアドキュメントを使って --prompt-file - 経由で渡してください（「プロンプトの渡し方」を参照）。送信後に Prompt sent (N chars) のエコーを確認してください。
• タスク ID を記録し、長時間実行されるタスクの状況を追跡するため、ターンをまたいで query_task を再実行してください。
• 署名付き動画 URL はそのまま保持してください。X-Amz-* パラメーターが含まれており、途中で切り詰めると機能しなくなります。
• エージェントはデフォルトの JSON 出力を優先してください。