picsart-api

Picsart API（MCP）

https://mcp.picsart.io/v1 上的 picsart MCP 服务将四个 Picsart REST API 公开为 MCP 工具。每个工具名称都与 OpenAPI 的 operationId 完全一致，保留连字符（例如 genai-text2image、image-remove-background、video-trim、vd-export-replay）。

适用场景

在用户要求以下操作时，使用此技能：

• 根据提示词生成全新内容——图像、视频、贴纸、徽标、语音、声音、音乐、SFX 或文本补全。
• 编辑、增强、调整大小、转换格式、重新着色或变换现有图像或视频。
• 移除背景或对象；进行图像修复、扩展，或扩展画布。
• 应用特效、蒙版、样式、调整、模糊、颜色／样式迁移。
• 提取、转录或处理视频中的音轨。
• 放大、提高 FPS、超分辨率，或增强人脸。
• 为媒体添加水印、裁剪、剪辑、拼接或调整大小以适配。
• 通过 Replay 批量渲染个性化创意素材。

如果请求涉及上述任何内容，请在调用任何 picsart-*、image-*、video-*、genai-* 或 vd-* MCP 工具之前，先阅读 references/ 中相关的文档。

前置条件

必须已连接 picsart MCP 服务，并准备好 Picsart API 密钥：

• MCP 服务。 此仓库在根目录的 .mcp.json 中提供服务配置。Claude Code 会在此仓库（或已安装的技能）处于作用范围内时自动加载该配置。对于其他宿主（Cursor、Codex）或手动设置，请注册一个名为 picsart、指向 https://mcp.picsart.io/v1 的 HTTP MCP 服务：

  {
    "mcpServers": {
      "picsart": {
        "type": "http",
        "url": "https://mcp.picsart.io/v1",
        "headers": {
          "X-Picsart-API-Key": "${PICSART_API_KEY}",
          "Accept": "application/json"
        }
      }
    }
  }
  

• API 密钥。 启动 Agent 前，请在环境中导出 PICSART_API_KEY。切勿将其硬编码——配置会在运行时插入 ${PICSART_API_KEY}。

• 两个服务，两种身份验证模式。 仓库根目录的 .mcp.json 注册了两个 Picsart 服务。请根据设置选择对应的服务：

  • picsart，地址为 https://mcp.picsart.io/v1——此技能使用的服务。通过 X-Picsart-API-Key: ${PICSART_API_KEY} 请求头进行身份验证（如上所示）。提供所有 image-*、video-*、genai-* 和 vd-* 工具。
  • picsart-gen-ai，地址为 https://api.picsart.com/gen-ai/mcp——生成式 AI 服务。通过 OAuth 进行身份验证：宿主（Cursor、Claude Code）会在首次连接时启动交互式登录；无需 API 密钥请求头。其工具与 picsart 服务的 genai-* 工具集有所重叠，因此每个会话请选择一种方式，不要混用。

运行方法

1. 确定用户的意图，并只阅读匹配的 references/ 文档（参见快速参考）。不要阅读任务不会涉及的工具集文档。
2. 在该文档的工具索引中查找准确的工具名称（即 OpenAPI operationId）。
3. 通过 picsart MCP 服务逐字调用该工具。对于异步工具，请依次调用对应的轮询工具，直到任务进入终态（参见流程）。
4. 将最终结果 URL 返回给用户。

快速参考

本技能的 references/ 文件夹中有四份参考文档，分别对应四个 API 接口：

• 图像 (references/image-api.md) — 移除背景、放大、特效、蒙版、调整、水印、裁剪、混合、分割、标记、矢量化、设计导入。基础 URL：https://api.picsart.io/tools/1.0。
• 视频 (references/video-api.md) — 编辑、修剪、裁剪、拼接、适配、特效、FPS 放大、缩略图、元数据、音频调整 / 提取 / 转录、CTV 编码、水印。基础 URL：https://video-api.picsart.io/v1。
• GenAI (references/genai-api.md) — 文本→图像、文本→贴纸、Logo 生成、图像编辑 / 修补 / 扩图、移除对象、智能背景、扩展 / 出血、文本→视频、图像→视频、文本→语音、文本→声音、文本→文本补全。基础 URL：https://genai-api.picsart.io/v1。
• 可变数据 (references/variable-data-api.md) — 使用 Picsart Replay 模板进行批量个性化渲染。基础 URL：https://vd-api.picsart.io/v1。

根据用户的意图加载相应文档：

任务意图	要阅读的文档
根据提示词生成图像、贴纸、Logo，或生成文本补全	references/genai-api.md
根据文本或图像生成视频	references/genai-api.md
根据文本生成语音或声音 / 音效 / 音乐	references/genai-api.md
使用提示词编辑图像；修补、扩图、移除对象、智能背景、扩展、出血	references/genai-api.md
不使用提示词转换现有图像 — 移除背景、放大、特效、蒙版、调整、水印、裁剪、混合、矢量化	references/image-api.md
描述图像、为图像添加标签、分割图像、分类图像，或提取图像颜色	references/image-api.md
编辑 / 修剪 / 裁剪 / 拼接 / 适配视频；应用视频特效；FPS 放大；缩略图；水印；CTV 编码	references/video-api.md
调整 / 提取 / 转录视频音频	references/video-api.md
使用 Replay 模板进行批量个性化渲染	references/variable-data-api.md

已知的提交 → 轮询器配对（权威列表请参阅各 API 文档）：

• genai-text2image → genai-text2image-getresult
• genai-text2sticker、genai-text2sticker-laser-engraving → genai-text2sticker-getresult
• genai-generate-logo → genai-generate-logo-getresult
• genai-image-edit、genai-image-inpainting、genai-image-outpainting、genai-remove-object、genai-smart-background、genai-expand-image、genai-generate-image-bleed → genai-image-inpainting-getresult
• genai-text2video、genai-image2video → genai-text2video-getresult
• genai-text2speech、genai-text2sound → genai-text2audio-getresult
• image-ultra-upscale → image-ultra-upscale-getresult
• image-design-import → image-design-import-getresult
• video-upscale-fps → video-upscale-fps-getresult
• video-transcribe-audio → video-transcribe-audio-getresult
• video-set-thumbnail → video-set-thumbnail-getresult
• 其他会返回 job id 的视频操作 → video-getresult（音频输出则使用 video-getaudioresult）。
• vd-export-replay → vd-export-replay-getresult
• vd-export-variable-data-content → vd-export-variable-data-content-getresult

流程

核心原则

1. 工具名称 = operationId。 在文档的工具索引中查找准确名称，然后通过 MCP 服务原样调用。连字符保持不变。
2. 必须轮询异步任务。 许多工具会返回任务 ID，稍后才完成。仅凭提交调用绝不能告诉用户“已完成”——务必继续调用配对的轮询工具，直到任务状态为 FINISHED / succeeded。
3. 输入：文件或 URL。 大多数端点接受上传的文件或 *_url 字符串（例如 image_url、video_url）。如果资源已托管在公共位置，优先使用 URL——可避免上传开销。对于用户自己设备上的文件，MCP 服务无法读取——你需要先获取 URL。打开上传小组件（picsart_upload_widget 或 mp_upload，取决于可用的连接器），并等待它返回 URL。完整流程（包括两轮握手）见 picsart-add-media。
4. 高成本调用前先查额度。 每个 API 都提供额度查询工具（image-credits-balance、video-credits-balance、genai-credits-balance、vd-credits-balance）。如果会话中的首次调用可能成本较高（视频生成、批量导出、大幅放大），请调用对应的额度查询工具，避免用户遇到 402 时措手不及。
5. 枚举值必须准确。 效果名称、宽高比、样式、音色和输出格式在文档中都是封闭枚举。原样复制这些值——不要改述。无效的枚举值会导致调用失败并浪费一次往返。
6. 优先使用专用工具，而非通用工具。 放大 4× 或更高倍率时，使用 image-ultra-upscale 而不是 image-upscale；处理人脸照片时，使用 image-face-enhance；剪辑视频时，使用 video-trim 而不是 video-edit。

异步轮询模式

1. 调用提交工具，并记录返回的 ID（字段名称可能不同：id、inference_id、transaction_id）。
2. 使用该 ID 调用配对的轮询工具。如果状态为等待中（IN_PROGRESS、PENDING 等），稍等片刻后再次调用。
3. 状态变为终态（FINISHED / succeeded / FAILED）时停止轮询。向用户提供结果 URL，或在失败时说明错误。

轮询时保持简洁——只需告知一次“仍在处理中……”，不要逐次播报轮询过程。

常见工作流（每个步骤都是一次 MCP 工具调用；具体参数名称请参阅对应 API 文档）

• 根据提示词生成图像 — genai-text2image → genai-text2image-getresult → 返回图像 URL。
• 根据提示词生成短视频 — genai-text2video → genai-text2video-getresult → 返回 mp4 URL。
• 为现有图像添加动画 — genai-image2video → genai-text2video-getresult → 返回 mp4 URL。
• 文本转语音（配音） — genai-text2speech → genai-text2audio-getresult → 返回音频 URL。
• 文本转音效／SFX／音乐 — genai-text2sound → genai-text2audio-getresult → 返回音频 URL。
• 移除照片背景 — image-remove-background（同步）→ 返回结果 URL。
• 放大图像 — 小幅放大或快速处理 → image-upscale（同步）；放大 4× / 8× 或处理量较大 → image-ultra-upscale → image-ultra-upscale-getresult。
• 使用自然语言指令编辑照片 — genai-image-edit → genai-image-inpainting-getresult → 返回图像 URL。
• 填充照片中的区域 — genai-image-inpainting → genai-image-inpainting-getresult。
• 将照片扩展至边缘之外 — genai-image-outpainting 或 genai-expand-image → genai-image-inpainting-getresult。
• 移除照片中的物体 — genai-remove-object → genai-image-inpainting-getresult。
• 转录视频音频 — video-transcribe-audio → video-transcribe-audio-getresult → 返回转录文本。
• 修剪／裁剪／拼接视频 — video-trim / video-crop / video-concat → 如果返回作业 ID，则使用 video-getresult 轮询。
• 从 Replay 批量生成个性化内容 — vd-export-replay → vd-export-replay-getresult。对于由变量数据驱动的批量任务：vd-describe-variable-data-content → vd-export-variable-data-content → vd-export-variable-data-content-getresult。

注意事项

• 不要仅凭提交响应就宣布成功。 异步作业会返回作业 ID；在告知用户任务完成之前，等待对应的轮询工具报告终态。
• 区分相似意图：
  • 没有提示词的“增强这张照片” → 图像 API（image-upscale、image-ultra-enhance、image-face-enhance）。
  • 使用自然语言指令“将这张照片编辑为……” → GenAI（genai-image-edit）。
  • 从静态图像中“移除背景” → 图像 API（image-remove-background）；从视频中移除背景 → 视频 API（video-remove-background）。
  • “扩展／加宽／填充边缘之外的区域” → GenAI（genai-image-outpainting、genai-expand-image、genai-generate-image-bleed）。
• 注意枚举值变更。 对效果名称、风格、语音或宽高比进行改述会浪费一次往返调用 — 请从文档中原样复制枚举值。
• 遵守限制和内容政策。 遵循 Picsart 开发者指南 — 不得生成禁止的内容。图像上传大小／格式限制：参见 references/image-api.md。视频时长、分辨率和编解码器限制：参见 references/video-api.md。GenAI 提示词长度上限、seed／数量限制和安全过滤器：参见 references/genai-api.md。变量数据批次大小和 Replay 兼容性说明：参见 references/variable-data-api.md。

验证

• 在回复中返回最终结果 URL。
• 对于异步作业，等待任务完成后再宣布成功。仅提交的响应不代表任务已完成。
• 按照原样保留返回的 URL — 这些 URL 带有签名且有时效限制。
• 如果用户未指定输出格式，则使用端点的默认格式（各文档中均有说明）。

参考资料

官方门户：https://docs.picsart.io/

用于编写此技能文档的规范来源：

• https://apidocs.picsart.io/picsart-image-tools-api.yaml
• https://apidocs.picsart.io/picsart-video-tools-api.yaml
• https://apidocs.picsart.io/picsart-genai-tools-api.yaml
• https://apidocs.picsart.io/picsart-variable-data-tools-api.yaml