picsart-add-media

添加媒体（上传小组件）

Picsart 的 MCP 工具使用的是 URL，而不是本地路径；而且大多数 Agent 宿主（基于浏览器的聊天、无法访问 shell 的 Claude Code、ChatGPT 网页版）也无法直接读取用户磁盘上的文件。解决办法是使用基于浏览器的上传小组件：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 媒体工具连接器上（工具前缀为 mp_*）。此版本没有 Drive 集成；其第二个标签页为“使用现有”，可从你传入的 known_urls 中选择，而不是浏览 Drive。

如果两个工具都已连接，任意一个都可以使用——优先选择当前工具列表中靠前显示的工具。如果两个都未连接，请如实告知；不要猜测工具名称。

如何运行

无需运行脚本——此技能只需调用一次工具，然后简短等待用户的下一条消息。

快速参考

参数	作用
(none)	打开小组件，不预填任何内容——显示普通的拖放界面
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 返回给你，但大多数 Agent 宿主只有在用户的下一条消息到达时才会传递该 URL——不会在当前轮次中立即返回。这是一个真正的双轮握手，不能通过轮询来等待。

可以这样说：“我已打开上传面板——请将文件拖入其中，并在完成后告诉我。”然后停止并等待。不要仅仅因为在调用工具的同一轮次中没有收到信息，就声称看不到文件或上传失败。

3. 将 URL 传给用户实际需要的工具

当 URL 返回后（即用户的下一条消息到达时），将其传入用户原始请求所需工具中对应的 URL 参数（image_url、video_url 等）。

易踩的坑

• 期待在同一轮中获得 URL。 不会有 — 请参阅第 2 步。提示用户并等待他们的下一条消息，不要过早报告失败。
• 把 detected_files 当作筛选条件。 它只是文件名的显示提示：这些文件你能看到，但无法获取。切勿依据此列表拒绝或质疑用户实际上传的文件。
• 重复索要已上传的文件。 打开小组件前，先检查对话中是否已有 URL — 将其通过 known_urls 传入，而不是重新开始。
• 猜测工具名称。 picsart_upload_widget 和 mp_upload 属于不同的连接器，功能确有差异（Drive 选项卡与“使用现有”选项卡）— 请查看实际连接的是哪个，而不是默认某个工具始终存在。

验证

• 打开小组件的工具调用已返回，且没有报错。
• 后续用户消息中返回了一个 URL，看起来像真实的托管链接（而非本地路径）。
• 接受该 URL 的下游工具调用没有因 URL 本身而失败。

相关内容

• picsart-api — 此技能会将 URL 提供给的 MCP 工具目录。