picsart-api

Picsart API（MCP）

https://mcp.picsart.io/v1 にある picsart MCP サーバーは、4 つの Picsart REST API を MCP ツールとして公開します。各ツール名は OpenAPI の operationId と完全に一致し、ハイフンもそのまま維持されます（例：genai-text2image、image-remove-background、video-trim、vd-export-replay）。

使用する場面

ユーザーが次のことを求めた場合は、このスキルを使用してください。

• プロンプトから新しいコンテンツ（画像、動画、ステッカー、ロゴ、音声、サウンド、音楽、効果音、またはテキスト補完）を生成する。
• 既存の画像や動画を編集、強化、サイズ変更、形式変換、色変更、または変換する。
• 背景やオブジェクトを削除する。インペイント、アウトペイント、またはキャンバスを拡張する。
• エフェクト、マスク、スタイル、調整、ぼかし、色やスタイルの転送を適用する。
• 動画内の音声トラックを抽出、文字起こし、または加工する。
• アップスケール、FPS アップスケール、超解像、または顔の補正を行う。
• メディアにウォーターマークを追加、トリミング、カット、連結、またはフィットする。
• Replay を使用して、パーソナライズしたクリエイティブアセットを一括レンダリングする。

依頼内容が上記のいずれかに関係する場合は、picsart-*、image-*、video-*、genai-*、または vd-* MCP ツールを呼び出す前に、該当する references/ ドキュメントを読んでください。

前提条件

picsart MCP サーバーが接続され、Picsart API キーが利用可能である必要があります。

• MCP サーバー。 このリポジトリには、リポジトリのルートに .mcp.json のサーバー設定が含まれています。Claude Code は、リポジトリ（またはインストール済みスキル）がスコープ内にある場合、自動的に読み込みます。他のホスト（Cursor、Codex）を使用する場合や手動で設定する場合は、https://mcp.picsart.io/v1 を指す picsart という名前の HTTP MCP サーバーを登録してください。

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

• API キー。 エージェントを起動する前に、環境変数として PICSART_API_KEY を設定してください。キーをハードコードしないでください。設定では実行時に ${PICSART_API_KEY} が展開されます。

• 2 つのサーバー、2 つの認証方式。 リポジトリのルートにある .mcp.json には、2 つの Picsart サーバーが登録されています。環境に合った方を使用してください。

  • https://mcp.picsart.io/v1 の picsart — このスキルが使用するサーバーです。X-Picsart-API-Key: ${PICSART_API_KEY} ヘッダー（上記参照）で認証します。すべての image-*、video-*、genai-*、vd-* ツールを公開します。
  • https://api.picsart.com/gen-ai/mcp の picsart-gen-ai — 生成 AI サーバーです。OAuth で認証します。初回接続時にホスト（Cursor、Claude Code）が対話形式のサインインを実行するため、API キーヘッダーは不要です。このサーバーのツールは picsart サーバーの genai-* ツール群と重複するため、1 回のセッションではどちらか一方を選び、混在させないでください。

実行方法

1. ユーザーの意図を特定し、該当する references/ ドキュメントのみを読んでください（クイックリファレンスを参照）。タスクに関係しない機能のドキュメントは読まないでください。
2. そのドキュメントのツール一覧で、正確なツール名（＝OpenAPI の operationId）を確認してください。
3. picsart MCP サーバー経由で、ツールを記載どおりの名前で呼び出してください。非同期ツールの場合は、ジョブが終了状態になるまで、対応するポーラーを連続して呼び出してください（手順を参照）。
4. 最終結果の URL をユーザーに返してください。

クイックリファレンス

4 つの API サーフェスに対応するリファレンスドキュメントが、このスキルの references/ フォルダーに 4 つあります。

• Image (references/image-api.md) — 背景除去、アップスケール、エフェクト、マスク、調整、透かし、トリミング、ブレンド、セグメンテーション、タグ付け、ベクター化、デザインインポート。ベース URL：https://api.picsart.io/tools/1.0。
• Video (references/video-api.md) — 編集、トリミング、クロップ、結合、フィット、エフェクト、FPS アップスケール、サムネイル、メタデータ、音声の調整／抽出／文字起こし、CTV エンコード、透かし。ベース URL：https://video-api.picsart.io/v1。
• GenAI (references/genai-api.md) — テキスト→画像、テキスト→ステッカー、ロゴ生成、画像編集／インペイント／アウトペイント、オブジェクト除去、スマート背景、拡張／塗り足し、テキスト→動画、画像→動画、テキスト→音声、テキスト→サウンド、テキスト補完。ベース URL：https://genai-api.picsart.io/v1。
• Variable Data (references/variable-data-api.md) — Picsart Replay テンプレートを使った一括パーソナライズレンダリング。ベース URL：https://vd-api.picsart.io/v1。

ユーザーの意図に合ったドキュメントを読み込んでください。

タスクの意図	読むドキュメント
プロンプトから画像、ステッカー、ロゴを生成する、テキスト補完を行う	references/genai-api.md
テキストまたは画像から動画を生成する	references/genai-api.md
テキストから音声、サウンド／SFX／音楽を生成する	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
• ジョブ 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 が返るまで待ちます。2 ターンのハンドシェイクを含む手順全体は、picsart-add-media を参照してください。
4. 高コストの呼び出し前にクレジットを確認します。 各 API には残高を確認するツール（image-credits-balance、video-credits-balance、genai-credits-balance、vd-credits-balance）があります。セッションで初めて、負荷が大きくなる可能性のある呼び出し（動画生成、一括エクスポート、長時間のアップスケールなど）を行う際は、該当する残高確認ツールを呼び出し、ユーザーが 402 エラーに不意を突かれないようにします。
5. 列挙値は正確に指定します。 エフェクト名、アスペクト比、スタイル、音声、出力形式は、ドキュメントで定義された固定の列挙値です。値をそのままコピーし、言い換えないでください。無効な列挙値を指定すると呼び出しが失敗し、往復が無駄になります。
6. 汎用ツールよりも専用ツールを優先します。 4×以上のアップスケールには image-upscale ではなく image-ultra-upscale を、顔写真には image-face-enhance を、動画のカットには video-edit ではなく video-trim を使用します。

非同期ポーリングの手順

1. 送信ツールを呼び出し、返された ID を取得します（フィールド名は id、inference_id、transaction_id などさまざまです）。
2. 対応するポーラーをその ID で呼び出します。ステータスが保留中（IN_PROGRESS、PENDING など）の場合は、少し待ってから再度呼び出します。
3. ステータスが終端状態（FINISHED / succeeded / FAILED）になったら終了します。成功時は結果の URL をユーザーに提示し、失敗時はエラーを伝えます。

ポーリングは静かに行います。「まだレンダリング中です…」という更新は 1 回で十分です。ポーリングのたびに状況を説明しないでください。

一般的なワークフロー（各ステップは MCP ツールの呼び出し 1 回です。正確なパラメーター名は各 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 を返します。
• テキストからサウンド／効果音／音楽を生成 — 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 を返します。ユーザーにタスクの完了を伝える前に、対応するポーリングツールで終端ステータスが報告されるまで待ってください。
• 似た意図を区別してください：
  • プロンプトを指定せずに「この写真を補正して」→ Image API（image-upscale、image-ultra-enhance、image-face-enhance）。
  • 自然言語の指示で「この写真を…に編集して」→ GenAI（genai-image-edit）。
  • 静止画の「背景を削除」→ Image API（image-remove-background）。動画の「背景を削除」→ Video API（video-remove-background）。
  • 「端の外側に拡張／幅を広げる／塗り足す」→ GenAI（genai-image-outpainting、genai-expand-image、genai-generate-image-bleed）。
• 列挙値のずれは呼び出しの失敗につながります。 エフェクト名、スタイル、音声、アスペクト比を言い換えると、余計な往復が発生します。ドキュメントに記載されている列挙値をそのままコピーしてください。
• 制限とコンテンツポリシーに注意してください。 Picsart Developer Guidelinesを遵守し、禁止されているコンテンツは扱わないでください。画像のアップロードサイズ／形式の制限については、references/image-api.mdを参照してください。動画の長さ、解像度、コーデックの制限については、references/video-api.mdを参照してください。GenAI のプロンプト長の上限、シード／件数の制限、安全フィルターについては、references/genai-api.mdを参照してください。Variable Data の一括処理のサイズと Replay の互換性に関する注意事項については、references/variable-data-api.mdを参照してください。

検証

• 最終結果の 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