picsart-add-media

メディアを追加する（アップロードウィジェット）

Picsart の MCP ツールではローカルパスではなくURLを使用します。また、ほとんどのエージェントホスト（ブラウザーベースのチャット、シェルアクセスのない Claude Code、ChatGPT web）は、ユーザーのディスク上のファイルを直接読み取ることもできません。この問題は、ブラウザーベースのアップロードウィジェットで解決できます。MCP ツールがユーザーのブラウザーにドラッグ＆ドロップパネルを開き、ブラウザーがファイルを Picsart の CDN に直接アップロードして、ウィジェットが生成された URL を返します。ファイルのバイトデータがツール呼び出しを経由することはありません。

使用するタイミング

「動画クリップが3つあります」「写真はこちらです」「私の映像を使ってください」「これらのクリップを組み合わせてください」といった、メディアがユーザー自身のもので、まだリンクを受け取っていないケースで起動します。

次の手順で URL（image_url、video_url、startFrame など）が必要で、対象がユーザーのマシン上のファイル、取得できないチャットの添付ファイル、または公開済みの https:// リンクではないものの場合は、いつでもこのウィジェットを利用してください。

前提条件

現在のツール一覧に Picsart MCP コネクターが含まれている必要があります。このスキルは、接続されている次のいずれかを呼び出します。

• picsart_upload_widget — Picsart MCP コネクター上で使用します（ツール名のプレフィックスは picsart_*）。このバリアントには、そのコネクターが Drive にアクセスできるため、「Drive に保存」オプションと Drive 閲覧タブもあります。
• mp_upload — Picsart media-tools コネクター上で使用します（ツール名のプレフィックスは mp_*）。このバリアントには Drive 連携はありません。2つ目のタブは Drive ブラウザーではなく、「既存のものを使用」（渡された known_urls から選択）です。

両方に接続されている場合は、どちらでも使えます。現在のツール一覧で先に表示されているほうを優先してください。どちらにも接続されていない場合は、その旨を伝えてください。ツール名を推測してはいけません。

実行方法

実行するスクリプトはありません。このスキルではツールを1回呼び出した後、ユーザーの次のメッセージを少し待つだけです。

クイックリファレンス

引数	機能
(なし)	入力済みコンテキストなしでウィジェットを開きます。通常のドラッグ＆ドロップ画面です
purpose	ドロップゾーンに表示するラベルです（例："product photo"）
accept	image、video、audio に制限します
detected_files	会話内で確認できるものの、自分ではアクセスできないファイル名（例：チャットの添付ファイル）です。ヒントとしてのみ表示されます
known_urls	会話中にすでに生成された URL を、選択可能なチップとしてあらかじめ表示します。利用可能なものをユーザーに再アップロードさせずに済みます

手順

1. アップロードツールを呼び出す

前提条件に従って picsart_upload_widget または mp_upload を呼び出し、該当する purpose、accept、detected_files、known_urls を指定します。引数はすべて省略可能です。引数を指定せずに呼び出すと、ウィジェットが開きます。

{ "purpose": "product photo", "accept": "image", "known_urls": ["https://cdn.picsart.io/…already-uploaded.jpg"] }

• detected_files はラベルのヒントにすぎず、フィルターではありません。モデルが指定するため、誤っていたり、幻覚によるものだったりする可能性があります。ユーザーは引き続き任意のファイルをドロップできます。detected_files の一覧になかったことを理由に、そのファイルは「受け付けられない」と伝えてはいけません。
• known_urls を渡すと再アップロードを避けられます。会話の前の段階で URL がすでに存在する場合（以前の生成結果やアップロードなど）は、ユーザーがファイルを探し直さずに選べるチップとして表示されるよう、ここに渡してください。

2. ユーザーに操作方法を伝えてから、次のメッセージを待つ

ウィジェットからアップロード済みの URL が返される仕組みは、多くのエージェントホストではユーザーの次のメッセージが届いたときにのみ利用できます。同じターン内ですぐに返されるわけではありません。これは実際に2ターンかかるハンドシェイクであり、ポーリングして待てる遅延ではありません。

「アップロードパネルを開きました。ファイルをドロップして、完了したらお知らせください」のように伝えてください。その後は停止して待ちます。同じターン内に何も届かなかったからといって、ファイルが見えない、またはアップロードに失敗したと主張してはいけません。

3. URL を、ユーザーが実際に使いたかったツールに渡す

URL が返されたら（ユーザーの次のメッセージで届きます）、ユーザーの最初の依頼に必要なツールの URL 用パラメーター（image_url、video_url など）に渡してください。

注意点

• 同じターンで URL が返ってくると期待すること。 URL は返ってきません。手順 2 を参照してください。早まって失敗を報告するのではなく、ユーザーにプロンプトを送信して、次のメッセージを待ってください。
• detected_files をフィルターとして扱うこと。 これは、確認できるものの取得できないファイル名を表示するためのヒントです。ユーザーが実際にドロップしたファイルを、このリストを根拠に拒否したり、疑問視したりしないでください。
• すでにアップロード済みのファイルをもう一度求めること。 ウィジェットを開く前に、会話内にすでに取得した URL がないか確認してください。最初からやり直すのではなく、known_urls 経由で渡してください。
• ツール名を推測すること。 picsart_upload_widget と mp_upload は異なるコネクターにあり、機能にも実際の違いがあります（Drive タブと「既存のものを使用」タブ）。どちらかが常に利用できると決めつけず、実際に接続されているものを確認してください。

検証

• ウィジェットを開いたツール呼び出しがエラーなく返された。
• その後のユーザーメッセージで URL が返され、実際にホストされたリンク（ローカルパスではない）に見える。
• その URL を受け取る後続のツール呼び出しが、URL 自体を原因として失敗しなかった。

関連項目

• picsart-api — このスキルが URL を渡す MCP ツールカタログ。