picsart_media_patch_scene

com.picsart.api/gen-ai · Verify this server

Apply a batch of incremental, ID-ANCHORED edit ops to an MP Scene and return the patched result — the token-cheap alternative to re-emitting the entire scene on every edit. Three verbs: `set` (create-or-replace a value; last-write-wins, idempotent; `replace` is accepted as a first-class alias), `remove` (delete a field/array element, or an entire anchored entity when no `path` is given), and `add` (insert a new id-keyed layer/asset/audio/marker; requires `kind` and a `value` carrying the new entity's `id`). Address the target with exactly one ANCHOR + id — `layer`, `asset`, `audio`, or `marker` — never a root index path: `{op:"set",path:"layers/3/..."}` is rejected with `use_id_anchor` and a corrected anchored form embedded in the message; omit the anchor only for true document-root fields like `composition/*`, `version`, or `scenes/<id>`. `path` is a slash-separated RFC-6901-style pointer relative to the anchored entity (e.g. `content/text`, `effects/0/params/amount`) — `~0`/`~1` escapes are honored, and dot-separated paths fail strict with a slash-form hint. All ops in one call are ATOMIC: they apply sequentially against a single clone and the first failing op aborts the WHOLE batch with no partial result (a typed error carrying `code` and `opIndex`); the input scene is never mutated, and later ops see earlier ops' results. Validation runs INSIDE this tool: the patched result goes through the exact picsart_media_validate_scene pipeline (JSON-Schema structural pass + semantic rules) and any severity:error fails the whole batch loudly with the diagnostics — a success has already passed that pipeline, so do NOT call picsart_media_validate_scene again right after a successful patch; only validate once you've made further hand-edits outside this tool. (Validation proves conformance to the scene contract, not that every referenced remote asset or scene_ref is fetchable at render time.) Id-less collections — track clips, `transitions`, `animations`, `keyframes`, text `content/animations` — carry no per-element id, so edit them with a whole-array `set` on the owning anchor's array path (e.g. `{op:"set",layer:"main_track",path:"content/layers",value:[...]}`) rather than addressing individual elements by index across calls.