picsart_asset_review
ChatGPTOpens the Picsart Asset Review board: a grid of generated assets where the user APPROVES the ones that work and sends the rest back for CHANGES. Two actions per tile, nothing else. Each tile is one asset's gridded sheet — every angle and state in one image — and approval on this board is what locks an asset: save each approved asset with picsart_save_asset, status: "locked". Normally pass DIFFERENT assets — a character, a location, a prop — one entry each, at most 12. The deliberate exception is a requested multi-model retry: put those sibling versions on the same board with the same tag and a model on every sibling. The reviewer chooses one and the board explicitly discards the other versions. Typical flow: generate one still per asset for a scene block, pass them all here in one call, then read the reply. Every tile comes back in approved, changes, or discarded; never save or regenerate discarded comparison siblings. For each change, regenerate THAT asset with its note folded into its own prompt, change nothing else, and open a FRESH board with just those — passing version ("v2") and previousUrl so the user can compare it with the earlier version and ask to go back. Repeat until changes is empty. Nothing is ever decided by silence: the board blocks its own send until every tile has a verdict. Pass Picsart-hosted https URLs only; other hosts are blocked by the widget sandbox. Returns the normalised board payload the widget renders. Read-only; spends no credits and works without authentication. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool, if it has one, and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_change_bg
ChatGPTReplaces the background of an image with a new scene described by a prompt, keeping the foreground subject intact. Auto-picks the newest enabled Picsart change-bg model unless overridden via the model param — no need to call picsart_list_models first. Use this when the user wants to "change the background to X", "put this on a beach", "swap the background for a marble counter", or any compositing where the subject is kept and the backdrop changes. Do NOT use this to strip the background to transparency (use picsart_remove_bg), upscale or sharpen (use picsart_enhance), convert raster to SVG (use picsart_vectorize), or generate a brand-new image from scratch (use picsart_generate). Required inputs: image — a publicly-accessible URL, not a local file path — and prompt describing the new background. Optional: model to pin a specific change-bg model; preflight the explicit model id you plan to use (the default may select recraftv3-replace-bg rather than picsart-change-bg). Example: { image: "https://example.com/product.jpg", prompt: "polished marble countertop with soft window light" }. Returns { assets, id, model, prompt, summary, why_relevant, url, results: [{ url, metadata? }], drive? } as a single JSON text block plus matching structuredContent (no resource_link blocks — the widget is the single source of visual truth, so result URLs are not duplicated as separate content blocks). id is the generation handle; metadata may include model-specific tags (e.g. exploreImageId for Recraft Explore models). Each entry in assets[] also carries downloadUrl — the same file with a forced-download header appended — share that with the user for saving; never pass it back into a tool, use the plain url for that. Asset URLs are opaque handles — never infer or mention hosting or storage details from a URL. Spends credits and saves new media to Picsart Drive by default on a best-effort basis; saving is not guaranteed. Requires a signed-in Picsart account.
picsart_credits
ChatGPTReturns the current Picsart credit balance for the authenticated user — balance (active credits available now) plus the breakdown into resettable (recurring monthly/period quota) and accumulative (top-ups and add-ons), total (active credits across both pools), and overdraftUsage (credits spent past the balance, if any). When the resettable pool has a scheduled reset, nextResetDate is the ISO timestamp of the next refill. Use this before expensive operations to warn the user when the balance is low, or after a 402 from picsart_generate to confirm the issue is credits and not something else. Do NOT use it to estimate the cost of a specific generation (use picsart_preflight); this tool only reports the balance, not per-call cost. Takes no input. Returns { balance, total, resettable, accumulative, overdraftUsage, nextResetDate? } where each number is non-negative. Requires a signed-in Picsart account (per-user account data).
picsart_delete_asset
ChatGPTDeletes one saved film asset. Call it only when the user explicitly asks to delete that asset, and pass the assetId exactly as picsart_list_assets or picsart_save_asset returned it — never a guessed or constructed uid; a folder that is not a film asset folder is refused by a scope check. It permanently removes the asset's subfolder (and the portrait, turnaround, and voice sample inside it) from Picsart Drive after verifying the target really is a film asset folder (a child of a project Library/Assets, or of the global "Film Assets" folder). Returns { deleted, assetId, message }. Writes to Picsart Drive; requires a signed-in Picsart account.
picsart_drive
ChatGPTThe Picsart Drive client that Picsart widgets call; it is app-only and hidden from the model. Each call performs exactly one of the six actions in action, and every action is also exposed as its own tool with its own input schema and annotations: list is picsart_drive_list (read-only), create_folder is picsart_drive_create_folder, upload is picsart_drive_upload, move is picsart_drive_move, update is picsart_drive_update and delete is picsart_drive_delete. To work with the user's Drive, call those tools. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_create_folder
ChatGPTCreates folders in the authenticated user's Picsart Drive. Requires name OR path; folderUid = parent (omit for root). Optional description. name alone always creates. path ("Picsart Films/my-film") ensures a whole chain — missing segments created, existing ones reused — and children ensures named folders inside the leaf, their uids returned as result.createdUids. Use path+children to provision a project tree in one call. Returns the listing of the folder just created — never its parent — plus result.createdUid. If the re-list itself fails, the listing is empty and result.staleListing is true -- that does not mean the change failed. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_delete
ChatGPTDeletes files or folders from the authenticated user's Picsart Drive. Requires itemUids. Soft-deletes to the trash (recoverable) unless permanent is true, which purges them for good. result.deleted lists the removed uids. Returns the listing of folderUid (omit = root) plus result. If the re-list itself fails, the listing is empty and result.staleListing is true -- that does not mean the change failed. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_list
ChatGPTLists one folder of the authenticated user's Picsart Drive and shows it in the Drive browser. Read-only. folderUid omitted = Drive root; set it to descend. Folders are returned first; files are paginated (page, pageSize<=128, optional sort, optional type filter). Set flat: true to list every file across all folders (folders are omitted in flat mode). Each file's url is its Picsart-hosted URL, ready to pass to picsart_generate reference params like imageUrls; its downloadUrl is the same file with a forced-download header appended — hand that to the user for saving, never pass it back into a tool. Preserve asset URLs verbatim when passing them into tools; URL structure does not establish durability. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_move
ChatGPTMoves files or folders within the authenticated user's Picsart Drive. Requires itemUids; targetFolderUid = destination (omit = root). result.moved reports each item and whether its move failed. Returns the destination folder's listing plus result. If the re-list itself fails, the listing is empty and result.staleListing is true -- that does not mean the change failed. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_search_mentions
ChatGPTFinds the signed-in user's own Picsart Drive files by name, most recent first, for attaching to a message. An empty query returns the most recent files. Requires a signed-in Picsart account.
picsart_drive_update
ChatGPTSets custom key/value attributes on one file in the authenticated user's Picsart Drive (e.g. { coverUrl }). Requires itemUid + attributes; a key that already exists is overwritten. Returns the listing of folderUid (omit = root) plus result.updated. If the re-list itself fails, the listing is empty and result.staleListing is true -- that does not mean the change failed. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_upload
ChatGPTSaves files into the authenticated user's Picsart Drive: one file, or up to 10 in ONE call via files: [{url, name, type?}] (always batch a set; the result's items[] reports each file's uid, URL, and durability). Single form: EITHER file (chat attachment) OR url+name (an HTTPS URL or an inline data: URI — data URIs are uploaded to Picsart first). folderUid = destination, type = resource kind. result.url is the Picsart-hosted URL of the saved file, ready to pass to picsart_generate reference params like imageUrls. result.downloadUrl is the same file with a forced-download header appended — hand that to the user for saving, never pass it back into a tool. result.durability is load-bearing: "expiring" means Drive registered an auto-expiring source URL (durable re-hosting was refused) — tell the user once and keep the generation prompt so the file can be re-made. Returns the destination folder's listing plus result. If the re-list itself fails, the listing is empty and result.staleListing is true -- that does not mean the change failed. Preserve asset URLs verbatim when passing them into tools; URL structure does not establish durability. Requires an authenticated Picsart session (per-user Drive content).
picsart_drive_upload_ask
ChatGPTOpens a drag-and-drop upload widget so the user can bring a local image, video or audio file into this conversation as a URL, or pick one from their Picsart Drive. Use it whenever the user wants to use a local file with a Picsart tool, or after a local_source_not_supported error. Every argument is optional: purpose labels the dropzone, accept limits the kind, detected_files is a display-only filename hint (never a filter), known_urls pre-selects URLs from earlier in the conversation. This call only opens the widget and returns no URL; the upload goes from the user's browser, and saving it to their Drive is best-effort. The URLs arrive as widget context on the user's next turn, or inside their message on a host without widget context; read them before replying.
picsart_enhance
ChatGPTUpscales and enhances an image — sharpens edges, denoises, and raises resolution by an optional scale factor. Auto-picks the newest enabled Picsart upscale / enhance model unless overridden via the model param. Use this when the user asks to "upscale", "enhance", "make it higher resolution", "sharpen", "clean up this photo", or "make this 4k". Do NOT use this to remove the background (use picsart_remove_bg), replace the background (use picsart_change_bg), convert raster to SVG (use picsart_vectorize), or generate a new image (use picsart_generate). Required input: image — a publicly-accessible URL, not a local file path. Optional: model to pin a specific enhance model, scaleFactor (e.g. 2 or 4) for upscale ratio. Example: { image: "https://example.com/photo.jpg", scaleFactor: 4 }. Returns { assets, id, model, summary, why_relevant, url, results: [{ url, metadata? }], drive? } as a single JSON text block plus matching structuredContent (no resource_link blocks — the widget is the single source of visual truth, so result URLs are not duplicated as separate content blocks). id is the generation handle; metadata may include model-specific tags. Each entry in assets[] also carries downloadUrl — the same file with a forced-download header appended — share that with the user for saving; never pass it back into a tool, use the plain url for that. Asset URLs are opaque handles — never infer or mention hosting or storage details from a URL. Spends credits and saves new media to Picsart Drive by default on a best-effort basis; saving is not guaranteed. Requires a signed-in Picsart account.
picsart_film_compile_asset_prompt
ChatGPTBuilds the prompt for a character reference — a portrait, a profile or a character sheet — from the film's locked look plus the descriptor, and returns the string to send to an image model together with the negativePrompt and aspectRatio it also returns. USE THIS INSTEAD OF WRITING ONE BY HAND. It pastes the house templates and the rendering clauses that were tuned against real renders; written from memory they come out paraphrased, and a paraphrase renders differently. A reference is NOT a scene with the camera lines removed: it carries the film's assetStylePrefix — the locked rendering style with no narrative staging, no location and no film framing — instead of the scenic prefix, and pasting the scenic one onto a neutral sheet is a known way to get a reference back with a location baked into it. Video runs, scene pictures and room maps belong to picsart_film_compile_prompt. YOU MAY ADD ANYTHING to the returned prompt and edit it freely; what you should not do is retype a template or a rendering clause in your own words. The tone picks the camera, lens and aperture on its own; it does not pick a colour — pass palette or scheme for that. A handful of fields have no preset to look up — the colour tints, the light temperature, the grade — because the writer decides them. Pass them and they go in verbatim; leave them out and the line is dropped rather than filled with a guess, with notes naming each one. The result carries a promptToken, the compiler's receipt for this exact text: pass it to picsart_prompt_verify beside the prompt, so the check can tell a compiled prompt from a retyped one. Read-only; spends no credits.
picsart_film_compile_prompt
ChatGPTBuilds a film generation prompt — a video run, a scene picture/still, a room map, or an edit — from your structured picks plus your own writing, and returns the finished string to send to picsart_generate, with a promptToken — the compiler's receipt for this exact text. Send the prompt verbatim, and pass the token to picsart_prompt_verify beside it so the check can tell a compiled prompt from a retyped one. Character portraits, profiles and sheets are built by picsart_film_compile_asset_prompt instead: a neutral reference carries the film's asset prefix, and pasting this scenic one onto it bakes a location into every shot that reference touches. Give look (genre/tone/palette/rig ids) and it assembles the STYLE line too — a tone is an era recipe that fills the rig on its own. USE THIS INSTEAD OF WRITING A FILM PROMPT BY HAND. It pastes the house lines and the camera/lighting/acting preset text that were tuned against real renders; written from memory those come out paraphrased, and a paraphrase renders worse. You supply everything only you can write: the scene, the geography, each shot's framing, action, lines and delivery. YOU MAY ADD ANYTHING, ANYWHERE — per-shot extra, whole filmConstraints lines, a note on any performance — and you may edit the returned prompt freely. What you should not do is retype a preset or a house line in your own words. It also derives the cut list and total length from each shot's sec, decides whether the global camera line is dropped (it is, when every shot has its own move), and returns notes for things it will not silently repair — a spoken line too long for its shot is reported, because sec belongs to the user. For a still it also returns the negativePrompt to pass alongside the prompt: the medium ban always, plus the lettering ban on everything EXCEPT a room map — a map's own prompt asks for a label on each side, and banning lettering there destroys it. A video kind returns none; that field is image-model-only and never goes in prose. Every result carries stylePrefix — the STYLE line exactly as it went into the prompt. Store THAT verbatim rather than rebuilding it later; a rebuilt line drifts. An unknown preset id or an unfilled placeholder is refused with a message naming it. Read-only; spends no credits.
picsart_film_list_assets
ChatGPTLists the user's saved Picsart film assets — pairs each portrait file with its sibling turnaround file (when present) and parses each portrait's asset manifest. Pass projectFolderUid (the film's Drive project folder) to read ONE film: scope then picks "library" (locked passports — the default, and what the film is built from), "assets" (the working record, every version) or "all". Omit it to read the flat global "Film Assets" folder, which holds assets saved without a project. Use when the user wants to see the assets they built earlier ("show my film assets", "open the asset library"), pick one to reuse, or manage them. Do NOT use it to create or edit an asset (an asset is saved with picsart_film_save_asset once approved on picsart_film_review_assets). Returns the asset configuration (models, voicePresets) alongside { items, total, byStatus }, so no second round trip is needed. Newest first. byStatus counts the rows by status (draft / review / locked / unknown) — it is the answer to "is this block ready to generate?", and a non-zero draft or review count against zero locked is a hole in the scene×assets matrix, not a detail.
picsart_film_review_assets
ChatGPTOpens the Picsart Asset Review board, where the user approves each generated asset sheet or sends it back for changes. Free; opens a panel. Pass the assets in one call, one entry each, at most 12; for a requested multi-model retry, put the sibling versions on one board with the same tag and a model on every sibling. Every tile comes back in approved, changes or discarded: lock each approved asset with picsart_film_save_asset (status: "locked") and never save a discarded sibling; after a change, put only the regenerated assets on a fresh board with version and previousUrl. Picsart-hosted https URLs only. The answer (asset_review_feedback) arrives on the user's next turn as widget context or in their message; read it before replying.
picsart_film_save_asset
ChatGPTSaves a film asset (a character, location or prop) to the film's registry in Picsart Drive, the only writer of what picsart_film_list_assets reads. status: "locked" files it in the project's "Library", anything else in "Assets". Lock an asset once the user approved its sheet on picsart_film_review_assets: one call per approved asset, with that sheet as portraitUrl. Read locked in the result, never saved: a draft or review save comes back locked: false with a remaining list. Writes to Picsart Drive; requires a signed-in Picsart account.
picsart_film_setup
ChatGPTOpens the Picsart Film Setup console: three look sections browsed as artwork (genre; tone — an era recipe that sets the RIG to a named period of cinema and adds one clause of its own, Auto by default; colour as a scheme and a hue wheel — monochromatic, analogous, complementary or triadic, built around a named hue. The colour is ALWAYS the user's: a tone brings the rig and nothing else, so picking an era never rewrites a colour already chosen, and the wheel is live whenever a scheme is. There are no palette presets on the console; the palette is auto unless a shot picks its own on the shot list), the delivery bounds every generation inherits (frame aspect ratio, total film duration, handles), a two-part camera rig (camera, lens family). The widget compiles the picks client-side into the film's style prefix — the exact text pasted word for word into every prompt of that world — and the user's decision arrives as widget context when they press Lock (film_setup_feedback: selections, stylePrefix, summary, verdict "locked"; selections.scheme and selections.hue arrive when the user chose a scheme — pass them as look.scheme / look.hue to picsart_film_compile_prompt). THIS IS THE FIRST CONSOLE THE USER SEES. It opens at the start of the film, BEFORE picsart_shotlist_board — the shot cards inherit its presets, so a shot list opened first asks for framing and colour from a vocabulary the film has not adopted yet. It needs only the script and the logline, which the film has from the start. When the film's look is locked later, that lock keeps what was set here rather than choosing it late; reopen the console with current only when the reference images genuinely argue for a different direction, or whenever the user wants to revise a look. One call per visual world. Every control opens on a defensible default, so the console is never blocked waiting for input; use suggested to replace those defaults with what the script, logline, or moodboard actually decides, one line of why each — and pass ratio whenever the user has named a format at all, since the frame is the one default that is visibly wrong when the user already said "vertical". Store the returned stylePrefix verbatim; never reword it. Returns the normalised console payload the widget renders. Read-only; spends no credits and works without authentication. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool, if it has one, and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_film_shotlist
ChatGPTOpens the Picsart Shotlist Board: the scenes' shots as editable cards the user reorders, edits and approves, with size, move, lens, focus, light, colour, length and composition as picture pills. Run picsart_film_setup first: the pills use its presets. Call it once per planning pass with every scene. The approval (shotlist_board_feedback) carries each scene's FINAL shot list with every shot's values: replace your stored list with it. It plans; takes are reviewed in picsart_scene_editor. The answer (shotlist_board_feedback) arrives on the user's next turn as widget context or in their message; read it before replying.
picsart_film_verify_prompt
ChatGPTChecks a film prompt's mechanical rules, the ones that are string matching or arithmetic, BEFORE you spend a credit on it. Free and read-only; it refuses nothing and returns a verdict table. Call it on the LITERAL arguments you are about to pass to picsart_generate, every time, for a video run, a scene picture, a reference sheet, a room map or an edit, with the promptToken picsart_film_compile_prompt returned: a compiled prompt edited by hand fails the token check, so change the compile inputs and compile again instead. Given the approved shot list, the saved assets and the model's limits, it also checks the cast, cuts, lines, voices and reference budget. semanticReviewRequired is always true: nothing here judges the writing, and skipped names every check that had no input.
picsart_generate
ChatGPTCreates new media from a prompt: one call is one run of the Picsart model named in model, and it returns that run's image, video, audio, or text result. Spends credits. Every call is this same operation — a prompt and any input media in, a new result out — and model only selects which engine renders it, as model does on picsart_enhance. All inputs are declared below; a value the selected model does not support is rejected before anything is charged. Choose model from the Picsart catalog (picsart_model_catalog). Background removal (picsart_remove_bg), background replacement (picsart_change_bg), upscale / enhancement (picsart_enhance) and raster-to-SVG conversion (picsart_vectorize) have their own tools. Required inputs: model (id) and prompt. Model-dependent optional inputs: duration (video seconds), aspectRatio (e.g. "16:9", "9:16", "1:1"), resolution (e.g. "1080p", "4k"), count (1–10 outputs — when the model has no native count, ONE call fans out N jobs server-side, so never loop picsart_generate to get N candidates; async fan-out returns jobs: [...] — put them all on picsart_render_monitor), quality, style, negativePrompt, imageUrls (input pictures — probed before dispatch: a picture with any side under 300 px, a contact-sheet thumbnail or a too-narrow crop off a character sheet, is refused with the fix and nothing is charged; on a video model that also takes a startFrame/endFrame, a frame mixed with reference media is refused before dispatch on Seedance — the provider rejects the mix after the wait — and a frame sent alone returns a warnings[] entry: only the people visible in that frame have a picture, so put the frame first in imageUrls, say "IMAGE 1 — START FRAME" in the prompt, and keep the face and outfit pictures beside it), videoUrl (an input video), enhancePrompt, generateAudio, and extra — the selected model's further named settings, such as startFrame, endFrame or voiceId, as picsart_model_params lists them for that model. Example (image): { model: "flux-2-pro", prompt: "a cat in a hat", aspectRatio: "1:1", count: 1 }. Example (video): { model: "kling-v3-pro", prompt: "a cat skiing down a mountain", duration: 5, aspectRatio: "16:9" }. Returns { assets, id, model, prompt, summary, why_relevant, url, results: [{ url, metadata? }], drive? } as a single JSON text block plus matching structuredContent; the media gallery displays the results without separate resource_link blocks. id is the generation handle; metadata may include extra tags about the result. Each entry in assets[] also carries downloadUrl — the same file with a forced-download header appended — share that with the user for saving (e.g. in a host that renders links only); never pass it back into a tool, use the plain url for that. Preserve asset URLs verbatim when passing them into tools; URL structure does not establish durability. A text result (a model whose mode is "text") is produced synchronously (async is ignored) and returned as the text content block plus text in structured content. Every image, video or audio result defaults to async: the call returns { job, status: "ACCEPTED" } immediately, and you poll picsart_job_status with the job handle until it completes (it then returns this same media payload). picsart_render_monitor displays job progress in a widget for image, video and audio jobs. Never re-submit ANY generation because a call seemed to hang or the host reported a timeout: the render usually completed and already charged — poll the handle; for a call you made with async: false, check Drive for the new file before any retry (a dropped response is not a failed render). Pass async: false only for a call you know finishes inside the host's window. Hosts that support widgets render images and videos in the Picsart media gallery; clients fetch the assets from URLs, never base64. Spends credits; media results are saved to the user's Picsart Drive by default on a best-effort basis unless saveToDrive: false, except an async job given a `f…
picsart_image_change_bg
ChatGPTReplaces the background of an image with a new scene described by a prompt, keeping the foreground subject intact. Every call is paid in credits. Auto-picks the newest enabled Picsart change-bg model unless overridden via the model param — no need to call picsart_model_show first. Use this when the user wants to "change the background to X", "put this on a beach", "swap the background for a marble counter", or any compositing where the subject is kept and the backdrop changes. Do NOT use this to strip the background to transparency (use picsart_image_remove_bg), upscale or sharpen (use picsart_image_enhance), convert raster to SVG (use picsart_image_vectorize), or generate a brand-new image from scratch (use picsart_generate). Required inputs: image — a publicly-accessible URL, not a local file path — and prompt describing the new background. Optional: model to pin a specific change-bg model; preflight the explicit model id you plan to use (the default may select recraftv3-replace-bg rather than picsart-change-bg). Example: { image: "https://example.com/product.jpg", prompt: "polished marble countertop with soft window light" }. metadata may carry model-specific tags (e.g. exploreImageId for Recraft Explore models).
picsart_image_enhance
ChatGPTUpscales and enhances an image — sharpens edges, denoises, and raises resolution by an optional scale factor. Costs credits per run. Auto-picks the newest enabled Picsart upscale / enhance model unless overridden via the model param. Use this when the user asks to "upscale", "enhance", "make it higher resolution", "sharpen", "clean up this photo", or "make this 4k". Do NOT use this to remove the background (use picsart_image_remove_bg), replace the background (use picsart_image_change_bg), convert raster to SVG (use picsart_image_vectorize), or generate a new image (use picsart_generate). Required input: image — a publicly-accessible URL, not a local file path. Optional: model to pin a specific enhance model, scaleFactor (e.g. 2 or 4) for upscale ratio. Example: { image: "https://example.com/photo.jpg", scaleFactor: 4 }.
picsart_image_remove_bg
ChatGPTRemoves the background from an image, returning a transparent cutout of the foreground subject. Spends credits on each call. Auto-picks the newest enabled Picsart remove-bg model unless overridden via the model param — no need to call picsart_model_show first. Use this when the user asks to "remove the background", "cut out the subject", or "make the background transparent". Do NOT use this to replace the background with a new scene (use picsart_image_change_bg), upscale or sharpen the result (use picsart_image_enhance), convert raster to SVG (use picsart_image_vectorize), or generate a new image from scratch (use picsart_generate). Required input: image — a publicly-accessible URL. Local files are not supported; if you only have a local file, first make it available as a public or app-authorized URL. Optional: model to pin a specific remove-bg model, outputFormat (e.g. "png"). Example: { image: "https://example.com/portrait.jpg" }.
picsart_image_vectorize
ChatGPTConverts a raster image (PNG, JPG) into an SVG vector. Each conversion uses credits. Auto-picks the newest enabled Picsart vectorize model unless overridden via the model param. Use this when the user asks to "vectorize", "convert to SVG", "make this a vector", or wants a scalable version of a logo or icon. Best results on logos, icons, and simple graphics — photographic images vectorize poorly and the user should be warned. Do NOT use this to remove the background (use picsart_image_remove_bg), replace the background (use picsart_image_change_bg), upscale a raster image (use picsart_image_enhance), or generate a new image (use picsart_generate). Required input: image — a publicly-accessible URL to a PNG or JPG (not a local file path). Optional: model to pin a specific vectorize model. Example: { image: "https://example.com/logo.png" }. The result is one SVG asset.
picsart_job_status
ChatGPTChecks a job: a generation started by picsart_generate, which returns asynchronously by default for every media model — image and audio as well as video — or a media job whose receipt named this tool in tools.jobStatus. Assistants and widgets poll this every few seconds with the returned job handle, passed back verbatim. A generation handle also needs the model it was submitted with; a media handle (kind: "media") needs nothing else. Polling only reads job results and existing Drive metadata; it never saves files, creates folders, or starts a job. While running it returns { status: "ACCEPTED"|"IN_PROGRESS", progress?: { percent, estimatedSecondsLeft } }. A finished generation returns the same media payload picsart_generate would have returned ({ status: "COMPLETED", assets, results, url, ... }), or an error for FAILED/CANCELED jobs. A finished media job returns status: "COMPLETED" with result exactly as that tool returns with async:false, or status: "FAILED" with a user-facing error. Only the job's owner can read it. Preserve asset URLs verbatim when passing them into tools; URL structure does not establish durability. Requires a signed-in Picsart account.
picsart_list_assets
ChatGPTLists the user's saved Picsart film assets — pairs each portrait file with its sibling turnaround file (when present) and parses each portrait's asset manifest. Pass projectFolderUid (the film's Drive project folder) to read ONE film: scope then picks "library" (locked passports — the default, and what the film is built from), "assets" (the working record, every version) or "all". Omit it to read the flat global "Film Assets" folder, which holds assets saved without a project. Use when the user wants to see the assets they built earlier ("show my film assets", "open the asset library"), pick one to reuse, or manage them. Do NOT use it to create or edit an asset (an asset is saved with picsart_save_asset once approved on picsart_asset_review). Returns the asset configuration (models, voicePresets) alongside { items, total, byStatus }, so no second round trip is needed. Newest first. byStatus counts the rows by status (draft / review / locked / unknown) — it is the answer to "is this block ready to generate?", and a non-zero draft or review count against zero locked is a hole in the scene×assets matrix, not a detail. Read-only; spends no credits. Requires a signed-in Picsart account.
picsart_list_models
ChatGPTShows the Picsart model catalog, across ALL modes (image / video / audio / text), in the Picsart Studio model-picker widget so the USER can browse, compare, and pick the model for picsart_generate. Each item carries id, name, mode, inputType, purpose, supportedAspectRatios/supportedResolutions (when the model declares an enum for that param) (and provider, badges, description when verbose is true). Every item carries purpose: generate (makes a new asset from a prompt), edit (changes an existing asset of the same medium) or utility (a fixed transform of an input asset). Filter on purpose: "generate" whenever the user wants something made; results are sorted with generate models first. Supports user-requested catalog browsing, cross-mode searches, and inspecting model forms. picsart_model_catalog returns catalog data without a widget; picsart_model_choice presents a shortlist of candidates for the user to choose from. Pass mode (image/video/audio/text) to show one output medium. Ratio/resolution constraints ride along in supportedAspectRatios/supportedResolutions, so you rarely need picsart_model_params just to check whether a model supports a given aspect ratio or resolution. Inputs (all optional): mode (filter to image/video/audio/text — text = LLM models that return generated text), purpose (generate/edit/utility — see below; PASS generate for any "make me a…" ask), provider (case-insensitive substring like "flux", "kling", "google"), acceptsImage (true → only models that take an image input), acceptsVideo (true → only models that take a video input), acceptsAudio (true → only models that take an audio input), inputType (exact match on a model's input→output media code), limit (1–100, default 20), verbose (default false; when true each item adds provider/badges/description). Example: { mode: "video", acceptsImage: true, limit: 10 } returns image-to-video models. Returns { items, total, truncated } — truncated is true when more matched than were returned; refine filters or raise limit (max 100) to see more. Read-only; spends no credits and works without authentication.
picsart_media_analyze_audio
ChatGPTReplies with a media job receipt by default, not the analysis: pass the receipt's job object verbatim to the status tool named in its tools.jobStatus, which reports progress and, once the job finishes, the same analysis this tool returns with async:false. Set async:false to wait for the analysis in this call instead. Measure what an audio track is doing: tempo (bpm) with a beat grid, musical key, and loudness/spectral energy curves over time. Accepts an audio file or a video with an audio track. This is acoustic measurement, not transcription and not a written description; for container facts (duration, codec, sample rate) picsart_media_probe_media is cheaper. By default it returns a summary (source, tempo, key, and the energy curves as urls to fetch); the per-event series (beats, onsets, bpm_curve) are opt-in via include because a single track can measure thousands of them. Values that could not be measured are omitted rather than guessed, with the reason in notes. Confidence values are returned alongside tempo and key — a low confidence on speech, ambience or an arrhythmic recording is normal and should be reported as uncertainty, not restated as fact.
picsart_media_apply_effect
ChatGPTApply a named effect (gaussian_blur, drop_shadow, stroke, ...) to a visual layer in a scene, with catalog defaults filled for any omitted params. Returns the updated scene with the effect merged into the target layer's effects[] -- re-applying the same effect id REPLACES it (idempotent), so params can be tuned without stacking duplicate effects. Param NAMES are the effect's own and are not interchangeable across effects (gaussian_blur takes blur, not radius): read them before choosing values from picsart_media_get_capabilities({ sections: ["effects"] }), whose supports.effects row gives every param's name, kind, min/max, default, the closed values set of an enum, and a description wherever the catalog states a unit or sense (e.g. fade fades the effect OUT: 0 is full strength). Each param is validated by kind and numeric range; an unknown effect id, unknown param, or out-of-range value is rejected, and an unknown-param refusal lists every param the effect accepts with its kind, range and default. Optionally confine the effect to a detected region with mask (see that field); the same supports.effects row carries each effect's mask support, since some do nothing without one, and the detectors themselves are under supports.maskProviders. Pure: takes the full scene by value, returns a new scene; no server-side state. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_apply_gradient
ChatGPTAuthor a validated gradient paint (gradientFill or gradientStroke) into a shape layer's item tree in a scene, minting the item so its two ramps, endpoints and type are encoded correctly. A gradient is NOT a whole shape: it fills (or strokes) the geometry above it in its scope, so this targets an EXISTING shape layer that already has top-level geometry (rect/ellipse/path/polystar) and inserts the paint after it. Colors go in stops (>=2, each #rrggbb); transparency is an INDEPENDENT alphaStops ramp (its offsets need not line up with the color stops) because a color stop has no alpha byte -- this is how a glow fades to transparent. type is 'linear' (default) or 'radial'; startPoint/endPoint are the gradient axis in content-local px (endPoint is also the radius reference for radial), and highlightLength/highlightAngle shape a radial highlight. Re-applying REPLACES the shape's same-family paint (a fill/gradientFill for paint:'fill', a stroke/gradientStroke for paint:'stroke') in place, so a gradient swaps a solid fill cleanly and re-apply tunes rather than stacks. Neither ramp animates; the gradient's endpoints, by contrast, animate through the shape-item keyframe channel once authored. Pure: takes the full scene by value, returns a new scene; no server-side state. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_apply_look
ChatGPTApply a composite 'look' (e.g. vintage_bw, light_leak, shimmer) to a layer OR a track clip (a clip is a full layer) whose content is one of the look's appliesTo kinds (media or scene_ref for every shipped look), at any depth — layerId resolves in every composition of the scene. A look wraps the layer's content in an isolated nested composition so the treatment hits the composited result as one image. mode:'reference' (DEFAULT) appends {look, params} to the layer's looks[] and KEEPS its content as the look's subject — nothing is baked; translate/preview/query expand it just-in-time, or picsart_media_resolve_looks bakes a self-contained scene. That keeps the scene small and the look editable (re-tune, drop, stack). mode:'expand' bakes the nested sub-scene now; on a track clip it bakes the clip's whole looks[] chain, changing only that clip and the sub-scenes it declares, and the clip keeps its slot (no start; its duration stays). Omit params for the catalog defaults; looks and their params are in picsart_media_get_capabilities (looksCompact, or a look:<id> section). A layer with its own effects/animations/transform/blendMode/mask takes a look normally; the one refusal is adjustmentLayer:true, which grades the layers BELOW it. 'reference' leaves those properties on the layer untouched. 'expand' moves transform/transforms/animations/blendMode/mask/motionBlur onto the wrapper and routes the layer's effects/contentEffects into an effected-source sub-scene the look reads as its subject — so they apply BEFORE the look, exactly once. picsart_media_resolve_looks on a 'reference' document renders the same result, every look body at the same size; generated ids may differ (a repeated chain can mint x in one and x_1 in the other, and inside an inline composition the resolver's ids carry its prefix). Pure: takes the scene by value, returns a new scene. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_apply_motion_preset
ChatGPTApply a named motion preset (glow_pulse, ken_burns, scale_pop, ...) to a visual layer in a scene. Returns the updated scene with the preset's animations + effects merged into the target layer. Each preset declares an appliesTo set of layer content kinds (text/media/color) -- mismatches are rejected with a clear preset_kind_mismatch error. Discoverable presets and their parameter shapes are listed under supports.motionPresets in picsart_media_get_capabilities. Pure: takes the full scene by value, returns a new scene; no server-side state. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_apply_scene_template
ChatGPTInstantiate a scene template with the supplied parameter bindings. Three modes: reference (DEFAULT, canonical) packages a scene-reference layer (kind:'scene_ref' with bindings + optional speed/trim/fit) to drop into a parent scene's layers[]; at translate/preview time the ref becomes its OWN nested composition (keeps its resolution/duration, fit/transform honoured — the template stays a reusable parameterized unit). For a STANDARD library template (mpscene://montage, …) the parent declares NOTHING; the translator resolves it from the registry. bootstrap returns a complete resolved standalone scene (substitutes every $eval, synthesizes asset entries for asset-typed parameters, strips the parameters declaration) — use it to bake an editable starting scene. inline MERGES the template's resolved concrete layers + assets INTO a target scene you pass (no scene_ref) and returns it — the 'bring a preset's editable layers into my composition' op (ids prefixed so nothing collides, brought-in layer starts offset by at). The template's own assets are carried in under prefixed ids with its layers' assetId refs rewired to them; an asset or composition of the target scene BOUND into the template arrives as the template read it, a copy of that declaration and never its id: inline on the content (content.asset) for a clip, a prefixed entry of its own for an asset_* parameter. The target's own assets stay as written. Use picsart_media_describe_scene_template first to learn what parameters the template accepts. Pure: returns either sceneRef or scene plus the applied parameter map. For the common video jobs — concatenating/merging N clips with per-clip trim and fit/align into one output — call picsart_media_quickstart with recipe:'concat_videos' FIRST. It returns a complete, validated parameters payload for mpscene://montage; you should not need picsart_media_describe_scene_template or picsart_media_get_scene_schema round-trips for that case. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_apply_text_animation
ChatGPTBake a named entrance text-animation preset (typewriter, fade_in_chars, slide_up_lines, ...) onto a text layer in a scene. Returns the updated scene with concrete animation entries appended to the layer's content.animations[]. TIMING: the baked animation starts at the text layer's local time 0 (the layer's start on the timeline) and runs for the preset's duration; no preset takes a delay, so to reveal the text later set the layer's start (with its duration) to the moment the reveal should begin. Discoverable definitions and their parameter shapes are listed under supports.textAnimations in picsart_media_get_capabilities, with the timing rule under supports.textAnimationAuthoring.timing. Ambient definitions are not baked by this tool because they resolve against the layer duration; attach one as a named source such as { preset: "wiggle", params: {} } in content.animations[]. Pure: takes the full scene by value, returns a new scene; no server-side state. Pass summary: true for a short inspection-only result without the edited scene.
picsart_media_contact_sheet
ChatGPTAuth is handled by the platform automatically — no token setup needed on your end. Renders a cheap multi-frame OVERVIEW of a scene as low-res jpeg thumbnails YOU CAN ACTUALLY SEE: each sampled frame comes back as an inline image content block (labeled with its scene time), alongside the machine-readable { frames: [{time, url, inline}] }. Two modes: pass times (PREFERRED — you usually know the interesting moments: clip seams, animation midpoints, entrance ends) to get one thumbnail per requested time, rendered concurrently — at most 8 per call (pass more and 8 of them are picked evenly; the rest are not rendered); or pass frames (default 8) for evenly-spaced sampling across the whole timeline. Those frames fall on whole seconds, so a scene shorter than frames seconds returns one frame per second. At most 8 come back as images; a larger frames (up to 24) lists the rest as urls only. Use it to eyeball pacing, seams, and content presence across the WHOLE timeline before exporting, in one call. Validate the scene first. Inline images are best-effort under a total size/count budget: a frame that fails to download, is oversized, or falls outside the budget still comes back with its url and inline: false in the JSON — a partially-inlined sheet is a SUCCESS, not an error, because the render has already happened. Do not retry this call just to get the missing pictures (that re-renders them for no benefit) — open those urls instead. Scope: this samples a scene you have already authored, to look at it. It is NOT a metadata probe — use picsart_media_probe_media first for a source clip's duration/dimensions/frame rate. Sparse-sampling frames here to discover duration is only the fallback when picsart_media_probe_media genuinely cannot determine it (every frame is a real GPU render). Use picsart_media_query_layout to check layer geometry, overlap and stacking order without rendering.
picsart_media_describe_scene_template
ChatGPTDescribe a single scene template by URI -- returns its declared parameters (with types, defaults, ranges, required flags, descriptions) and composition dimensions. Use this before picsart_media_apply_scene_template so you know what to pass. Accepts mpscene://<id> URIs in v1; other schemes are deferred. Returns { id?, uri, composition, parameters } where parameters is the full declarations map.
picsart_media_describe_video
ChatGPTReplies with a media job receipt by default, not the description: pass the receipt's job object verbatim to the status tool named in its tools.jobStatus, which reports progress and, once the job finishes, the same description this tool returns with async:false. Set async:false to wait for the description in this call instead. Describe what is happening in a video: subjects, setting, actions, on-screen text, mood, pacing, and dominant colors. The content-understanding counterpart to picsart_media_probe_media (which reports container facts only — dimensions, codec, duration — never what is actually shown). Also returns a suggestedAspect you can feed straight into picsart_media_reframe_video, and, when question is given, an answer field addressing it specifically. Not a transcription tool: it describes visual content and never transcribes speech — for that, use picsart_media_transcribe. Charges credits on every call.
picsart_media_diff_layouts
ChatGPTCAN BE UNAVAILABLE: it resolves through picsart_media_query_layout, so it fails whenever that tool is unavailable (that tool says what to do instead). Diffs the resolved LAYOUT of two scenes (two storyboard boards) and reports, per layer, WHAT CHANGED — the geometry a motion author needs instead of hand-diffing coordinates. Resolves BOTH exactly as picsart_media_query_layout does (root-space, top-left-pixel boxes and centres, any engine), matches each layer of A to one in B, and classifies it moved / resized / restyled / content-changed / unchanged, or entered (B only) / exited (A only). Matching order: explicit matchHints, then same content id + kind (same asset/text), then geometry (best IoU / nearest centre) — NEVER layer id, since ids differ across independently-authored boards. A matched layer carries delta { dPos:[dx,dy], travelPx, dScale, dScaleXY, dRotation, dZ, visibilityChanged, contentChanged }, in root-space top-left pixels with centre-based positions. A whole-pair relationship (shared-layers / zoom-detail (B ≈ a uniform re-scale of A) / in-place-emphasis / unrelated / indeterminate) routes smart-animate vs camera vs cut. indeterminate means no comparison was possible (a board offered no layer with geometry; see notes), NOT that the boards differ — two identical text-only boards reach it on jet; boards whose comparable layers do not pair report unrelated. Geometry only: it recommends and applies nothing — turn deltas into motion with picsart_media_patch_scene / picsart_media_apply_motion_preset / picsart_media_apply_text_animation. Inherited from picsart_media_query_layout: no numeric opacity (restyle is detected via visibility + rotation), and text boxes are unmeasured on jet and font-metric envelopes on v3, so text deltas are approximate. Each scene resolves at one time (default 0); pass timeA/timeB for animated boards.
picsart_media_discover_fonts
ChatGPTDEPRECATED: use picsart_media_list_fonts, which searches the built-in catalog and Picsart's live font catalog in one call (its live.fonts). Search Picsart's font catalog (in-house fonts first, then Google Fonts) for a face that is NOT in picsart_media_list_fonts. FREE faces only: an in-house face flagged paid is never returned, and Google Fonts faces count as free by license even where the shop prices them. Each result carries asset, a ready-to-paste font asset { type: "font", name, uri } whose name is the face's own name and uri its .ttf/.otf file URL: add it to the scene's assets with an id and put that id in a text layer's font.family — that keeps the font's NAME. Omit query for the font-chooser shelves; a query matches by word start on each face's names and, when the shelves are short of limit, also searches the shop (up to 3 pages), under the same rule. A face served at two URLs is listed once. examined and the note say how many items were read versus returned. Network tool: searches Picsart's live font catalog. Results vary over time (stochastic).
picsart_media_expand_scene_ref
ChatGPTDETACH a scene_ref into editable layers: replace a resolvable scene_ref layer (or every one, if no layerId) with the referenced scene's resolved layers, ids prefixed by the ref layer's id. A ref that carries only id, start, duration and its reference, drawn at the host's size, frame rate and shutter-sample count and no longer than its scene (its composition.duration, else its latest explicit layer end), detaches FLAT: its layers join the parent's stack, started at the ref's start and ended by its duration. Any other ref (a transform, bounds, fit, animations, effects, a mask, a different size, rate or sample count) stays as the SAME layer with content changed to an inline composition holding the layers, the scene's own size, fps, duration and sample count on content.composition (bounds stays on content), so its placement and window still apply once; the layers keep their own times inside it. The scene's own assets come in under prefixed ids, its layers' assetId refs rewired; a caller asset or composition BOUND into it arrives as the scene read it — a copy of the caller's declaration, never the caller's id: inline on the content (content.asset) for a clip, a prefixed entry of its own for an asset_* parameter. Caller assets stay, even unused ones. One level per call: a brought-in scene_ref stays a reference, listed in stillReferenced; detach it by layerId. A track clip's reference is not detached. A referenced composition.background becomes a bottom color layer, <layerId>____background. Does NOT fetch: it resolves only mpscene:// refs (in the document or the registry). A remote http(s):// ref is left as-is; translate, render-preview and query-layout resolve it. An unresolvable ref is left as-is in bulk mode, an error in single-layer mode. Pure.
picsart_media_export
ChatGPTReplies with a media job receipt by default, not the render result: pass the receipt's job object verbatim to the status tool named in its tools.jobStatus, which reports progress and, once the job finishes, the same render result this tool returns with async:false. Set async:false to wait for the render result in this call instead. Only an async:false export is saved to Picsart Drive automatically; a finished job offers the Drive save instead. Render a fully-authored scene to a final file on Picsart's servers, returning the output URL(s). The output container is chosen with mediaType: omit it (default) to render an MP4, or pass mediaType:"png" for a single still (mov/webm/jpeg/webp/heif/gif/image-sequence are also accepted). This performs the ACTUAL render: the scene is dispatched to the export service over an authenticated HTTP call — no local renderer. Auth is handled by the platform automatically — no token setup needed on your end. Validate the scene (picsart_media_validate_scene) and check a frame (picsart_media_contact_sheet with times:[t] — sample one frame near the point you want to verify; it returns that frame as an inline image you can look at) BEFORE exporting. For a signed-in caller, an eligible single output is also saved to Picsart Drive on a best-effort basis. A failed or skipped save does not fail the render; only report a successful save when driveUid is returned. If you do not yet have a scene, get the whole sequence from picsart_media_quickstart rather than reverse-engineering the document shape from picsart_media_get_scene_schema. Every url in urls may also appear at the same index in downloadUrls — the same file with a forced-download header appended. Hand a downloadUrls entry to the user for saving (e.g. in a host that just renders links); never pass it back into another tool call, use the matching urls entry for that. downloadUrls is present only when the render landed on a Picsart-hosted url. Asset URLs are opaque handles — never infer or mention hosting, CDN or storage details from a URL.
picsart_media_flow_diff
ChatGPTCompares the motion structure of reference video a and candidate b over one window: fade versus movement, direction and sequencing. Returns a score, clustered findings and events, with details at resultUrl; with fps "auto" each fragment of a is scored on its own rather than in one combined score. It is not a pixel-equivalence test. Replies with a media job receipt by default, not the score: send the receipt's job unchanged to the status tool named in tools.jobStatus; async:false waits for the score in this call. Charges credits on each call.
picsart_media_get_capabilities
ChatGPTReturns this tool layer's capabilities: layer content kinds, animatable properties, the effect/transition/look catalogs with their params, per-feature format notes, and limits — the sizes the pipeline is exercised at, none of them enforced (see its enforced note). Call it when planning a composition. Omitting sections returns the section INDEX — every section name, top-level and supports sub-keys alike — plus a hint with the full document's current size and of every section too large for one answer. The document is large: pass sections for the slices you need, preferring granular supports sub-keys over the whole supports block (e.g. ["effects","limits"], ["textAnimations"], or ["generativeTemplates","limits"] for a montage plan — generativeTemplates holds parametric layout templates such as montage and collage, with no AI generation), or ["all"] for everything. looks alone (full prose + param schemas for every look) can overflow a result cap even as the one section requested — ask looksCompact first (id/summary/appliesTo/fade plus each param's name, type (with animatable), min/max and default); only a param declared animatable: true takes keyframes/an expression, every other is static-only. For one look's full entry use a look:<id> token in sections (see that param). Every answer carries build, the package version that produced it, so two answers to this call that differ can be told apart by their build. Idempotent and dependency-free; safe to cache.
picsart_media_get_recipe
ChatGPTFetch one recipe by name -- its full markdown body (the authoring instructions) plus the list of any companion reference files it links to (e.g. references/motion-rules.md). Call this after picsart_media_list_recipes has identified a relevant recipe from its metadata. Pass the optional reference argument (one of the returned referenceFiles paths) to fetch that companion file's raw content INSTEAD of the body -- this lets an agent pull extra detail on demand rather than loading everything a recipe carries up front. Returns { name, description, metadata?, body, referenceFiles }, or { name, reference, content } when reference is given.
picsart_media_get_scene_schema
ChatGPTReturns the JSON Schema for a scene. Use it to build a scene or to check the shape of layers, animations, effects and transitions. The schema is authoritative for STRUCTURE only. Passing it does not mean a document renders, and schema validity does not guarantee successful rendering: semantic rules live in picsart_media_validate_scene, and some of the schema's own field descriptions name values it structurally admits and the validator then rejects (font.family is a bare string in the schema, but a CSS-style name like 'Arial' is an unknown_font_family error). Always run picsart_media_validate_scene before rendering. The whole document carries every definition and is large, so prefer one of the narrower views: name returns that definition plus every definition it references, self-contained and validator-ready, while that stays under 60,000 characters; past that (MpScene, MpVisualLayer, MpAsset, a track or scene_ref content, which reach most of the schema) it returns the definition and its DIRECT references only, with partial saying so and notIncluded naming the rest to fetch by name. summary: true returns field names and types with no prose, plus rules (a field's one-line rule its type cannot show, e.g. when a clip's omitted duration is legal) and typeArguments (what a Name<Arg> argument means). Read summary first to find the definition you want, then fetch that one by name. A Name<Arg> is one definition, fetched by that full spelling; asking for a bare type argument such as MpDefinitionValues answers what it means and which definitions carry it. A Type.field pointer such as MpClip.cameraExempt (the form descriptions use) answers that one property: its schema and description, whether it is required, and the type that declares it. A type built on another states the relation rather than repeating it: allOf over the base's <Base>Fields list plus its own fields (false marks a base field it drops), or, for a type that re-types base fields, a $ref from each field it takes over unchanged to the base's.
picsart_media_import_figma_paint
ChatGPTConvert a Figma element's CSS paint (a panel's CSS paint from the design file the user shared) into scene items on a layer, instead of baking the element to an opaque SVG that cannot animate, scale or recolor. Three paints map cleanly and are applied; a fourth has no scene primitive yet and is reported, not dropped: fill (a CSS color, e.g. 'rgba(0,0,0,0.5)' or '#ff47ff') becomes a shape fill (a shape paint's color is RGB-only, so any alpha is stored in the fill item's opacity); boxShadow (a CSS box-shadow, one layer or a comma-joined list) becomes a drop_shadow effect for OUTER shadows, while an INSET shadow is returned in skipped because there is no inner-shadow primitive yet (keep the SVG for that one glow); gradient (a CSS 'linear-gradient(...)' or 'radial-gradient(...)') becomes a gradientFill (or gradientStroke). fill and gradient need a shape layer since they are shape items; a gradient also needs the element size [w,h] because CSS carries only an angle, not box-local endpoints. Returns the updated scene, applied (the item/effect types created), and skipped ({what, reason}) so you know exactly which treatments still need a bake. Pure: takes the full scene by value, returns a new scene; no server-side state.
picsart_media_import_svg_path
ChatGPTConvert an SVG path-data string (the d attribute) into scene path shape item(s) on a shape layer, instead of baking the outline to an opaque SVG asset that cannot animate, scale or recolor. Parses the FULL SVG path grammar, absolute AND relative -- M m L l H h V v C c S s Q q T t A a Z z, with repeated coordinate sets after one command letter: quadratic curves (Q/q/T/t) are elevated to cubics, elliptical arcs (A/a) are decomposed to cubic beziers, and the smooth shorthands (S/s, T/t) reflect the previous control point. Each SUBPATH (every new moveto) becomes one path item -- the model spells a bezier outline the Lottie/AE way ({ closed, vertices: [{ point, inTangent, outTangent }] }, tangents RELATIVE to their point, content-local px) -- and a closed subpath folds its closing tangent onto the start vertex. A path is geometry only; pass color for a solid #rrggbb fill (with fillRule 'evenodd' when the source SVG sets fill-rule="evenodd") and/or stroke + width for an outline. With either paint, the paths and their paint are appended together as ONE group item, so the paint reaches only the imported outline and never repaints the layer's existing shapes; with neither, the bare paths are appended for you to paint. For a GRADIENT outline, import geometry-only (no color/stroke) onto a dedicated shape layer, then call picsart_media_apply_gradient on it: a gradient is a top-level paint and cannot reach paths nested inside the paint group (and a top-level paint also covers any other top-level geometry on that layer). Transparency goes in fillOpacity / strokeOpacity (SVG fill-opacity / stroke-opacity), since a paint color carries no alpha byte. Genuinely unparseable input fails LOUD (invalid_path_data) rather than emitting wrong geometry. Returns the updated scene, applied (the item types created, e.g. ['path','fill','group']), and skipped ({what, reason}) for any subpath that had no drawable outline. Pure: takes the full scene by value, returns a new scene; no server-side state.
picsart_media_inventory_diff
ChatGPTCompares what is visible in reference video a and candidate b at up to 32 times: missing and extra elements, and differences in color, size, position and text, with a score and detailed findings at resultUrl. Both videos must have the same frame size. It judges appearance; picsart_media_flow_diff judges motion. Replies with a media job receipt by default, not the findings: pass the receipt's job verbatim to the status tool in tools.jobStatus; async:false waits for the findings here. Every call is billed in credits.
picsart_media_layout_lint
ChatGPTCAN BE UNAVAILABLE: it samples picsart_media_query_layout, so it fails whenever that tool is unavailable (that tool says what to do instead). Detects UNINTENDED layer overlaps over TIME and CLASSIFIES every overlapping pair rather than suppressing any. Samples picsart_media_query_layout over a window (default the whole composition, step 0.25 s) and, per sample, considers visible+active+on-canvas layers. Pairs are compared only within the same composition scope (picsart_media_query_layout's field): a nested scene_ref/look's inner layers against each other, never against the caller's, while the nested reference's own box IS compared with its top-level siblings. Each pair is classified over its overlap lifetime as exactly one of: containment (one box holds ≥90% of the other for ≥80% of their shared visible time — a chip in a bar, a badge on a card) or backdrop (the paint-order-lower layer covers ≥85% of the canvas — a full-bleed plate), both intentional and not flagged; transient (under 0.4 s, e.g. a handoff crossing), reported as info; collision (a sustained ≥0.4 s overlap between peers with IoU ≥ iou), FLAGGED under findings. allow: ['idA:idB', …] suppresses a specific pair (order-insensitive); it still appears under allowed with its real classification. A LINT, not a gate: found overlaps never fail the call; it fails loud only for an unreadable scene, a non-positive duration, an empty sampling window, or an engine/query error. Before trusting a clean report: on jet TEXT layers are not measured and are excluded from every comparison (noted); on v3 text boxes are font-METRIC envelopes, not glyph bounds, so a text overlap can be conservative; rotated layers compare by their axis-aligned envelope. Each sample is a full query, so narrow t0/t1 to the suspect region on long timelines.
picsart_media_list_fonts
ChatGPTFinds fonts for text layers: the built-in catalog, plus (on page 1) a live search of Picsart's font catalog, in-house faces and Google Fonts. Use this before authoring any text layer so font.family resolves to a real font. The renderer has no system-font fallback -- passing CSS family names like Inter, Arial, or Helvetica produces empty text and a unknown_font_family validation error. fonts is the built-in catalog, paged: at most pageSize entries (default 50, max 200) plus total, page, pageSize and hasNext -- pass page to read on. Each has a stable key, passable directly as a text layer's font.family, and a resolved .otf/.ttf URL. live.fonts holds the faces the live search found that the catalog does not already list: each carries a ready-made asset -- add it to the scene's assets[] with an id and put that id in font.family (an entry that also has a key can use the key instead). live.status is unavailable when the search failed; the catalog page still stands. No face is listed twice, within or across the two lists. Every entry has a source (catalog, picsart or google) and may carry a licenseType (commercial or personal) for usage-rights filtering. Live entries also carry paid (a Picsart subscription face); those are listed only to a signed-in caller -- for an anonymous one they are left out of live.fonts, and live.paidHidden is true when any were. Built-in catalog entries carry no paid flag and are listed to every caller: their licenseType is the usage-rights signal. Agents may also pass a direct font URL matching accepted_url_pattern. Narrow with query (substring of key or display name), family (e.g. "Roboto" for all its variants) and licenseType instead of paging through the whole catalog.
picsart_media_list_recipes
ChatGPTEnumerate the curated recipe registry -- reusable authoring know-how guides (Agent Skills-format markdown, e.g. how to turn a Figma storyboard into an animated scene) written for this toolset's own commands. Each entry is the METADATA TIER ONLY: name, description, and any category/version declared in the recipe's frontmatter metadata map -- no body text, so the whole catalog stays small enough to read in full before deciding which recipe is relevant. Call picsart_media_get_recipe with a chosen name to fetch its full instructions. Pure: no inputs, no state.
picsart_media_list_scene_templates
ChatGPTEnumerate the curated scene template catalog. Each entry summarises a reusable, parameterized scene (title cards, lower thirds, product cards, ...). Use this to discover templates by id/category/aspect before describing or applying one. Returns { templates: [{ id, displayName, description, category?, width, height, parameterCount }, ...] }. Pure: no inputs, no state.
picsart_media_patch_scene
ChatGPTEdit a scene with a batch of ID-anchored ops and get the patched scene back inline as scene. Atomic, validated inside. Verbs: set (create-or-replace, last-write-wins, idempotent; replace is an alias); remove (a field or array element, or the whole anchored entity when no path is given); add, either ANCHORLESS (a whole new entity: kind plus a value carrying its id) or ANCHORED (ONE element into an array inside an entity: anchor + path to the array, no kind) — {op:"add",layer:"reel",path:"content/clips",value:{…},after:"clip_a"} adds one clip without re-sending the rest. Address the target with exactly one anchor + id, layer or asset (a sound is a layer, content.kind:"audio"), never a root index path: {op:"set",path:"layers/3/..."} is rejected with use_id_anchor and the corrected anchored form in the message. Omit the anchor only for document-root fields (composition/*, version). A sub-scene is an asset: create it with an anchorless add of kind:"asset" and a type:"scene" value, remove it on its asset anchor, edit inside it with scope. path is a slash-separated RFC-6901 pointer relative to the anchored entity (content/text, effects/0/params/amount); a dot-separated path fails with a slash-form hint. Ops apply in order to one clone, later ops seeing earlier results; the first failing op aborts the WHOLE batch with a typed error (code, opIndex) and no partial result, and the input is never mutated. The result runs the full picsart_media_validate_scene pipeline (schema, semantic rules, the font-metric text-fit lint), and an error the patch introduces fails the batch; one the input already held comes back as valid:false, so a scene is repaired patch by patch. A valid:true success needs no picsart_media_validate_scene after it. Validation proves the scene contract, not that remote assets or scene_refs are fetchable.
picsart_media_probe
ChatGPTReturns a remote media URL's metadata from bounded, SSRF-guarded ranged reads (public http(s) only, every redirect re-checked; a data: URI is read in place, with no fetch). Free. Returns kind (image/svg/video/audio/lottie, as a scene asset type), as-displayed width/height (EXIF orientation applied, plus the raw orientation), durationSeconds (mp4/mov/m4a, fragmented MP4 included; Lottie up to 256 KiB), contentType and bytes, plus fps, videoCodec, audioCodec and hasAudio when the container states them. An unrecognized container returns kind/contentType/bytes and a notes[] entry; dimensions are never invented. An absent durationSeconds means unknown, never 0: resolve it another way before computing trims. Not needed when an earlier result already gave the exact size and duration. Marked stochastic only because a URL's content can change.
picsart_media_probe_media
ChatGPTReturns a remote media URL's metadata using bounded network reads: kind (image/video/audio), as-displayed width/height (EXIF orientation applied, plus the raw orientation), durationSeconds (mp4/mov/m4a), contentType, and total bytes — using ranged reads where supported, with response-size and time limits; fragmented MP4s can require additional reads. Provides source dimensions and duration for sizing compositions, choosing fit, setting clip windows, and checking whether an asset matches the scene requirements. Covers PNG/JPEG/GIF/WebP/HEIC/AVIF/SVG/TIFF dimensions and ISO-BMFF (mp4/mov/m4a) dimensions+duration, including moov-at-end files. Unrecognized containers still return kind/contentType/bytes plus a notes[] entry — dimensions are never invented. URLs are SSRF-guarded (public http(s) only; every redirect hop re-checked). Marked stochastic only because a URL's content can change between calls — probing an immutable asset is stable. Skip this call if you already know the asset's exact width/height/duration from a prior tool result (e.g. a generation tool's own response) — this is a cost-saving lookup, not a required gate. A missing durationSeconds means the duration is unknown — it is never emitted as 0 for a real zero-length clip. Fragmented MP4 / streaming uploads carry no duration in their container header, but this tool now recovers it for most of them by walking the file's fragment timeline, so a duration usually comes back anyway; when the field is still absent it genuinely could not be determined. That pass costs a few more small ranged reads — still bounded and free. Do not assume 0; resolve it another way before computing trims. The response may also carry fps, videoCodec, audioCodec and hasAudio when they are derivable from the container — these are best-effort extras and are omitted rather than guessed.
picsart_media_query_layout
ChatGPTCAN BE UNAVAILABLE: if layout resolution is unavailable, the call fails, and retrying with a different engine does not help. A rendered frame (picsart_media_contact_sheet) still answers whether content is there and looks right, and the authored positions are in the scene itself. Resolves each layer's geometry in the root composition at a given time without rendering pixels: root-space box {x,y,width,height} (top-left pixels), center, rotationDeg, paint-order zIndex, visible/active, onCanvas, timing and hierarchy. Use it before checking a rendered frame (picsart_media_contact_sheet) to verify placement, overlap, canvas coverage and stacking. Coordinates are top-left pixels in root space for every engine value; engine never changes the convention. Nested children are namespaced and returned individually; inactive layers have active:false and no box. verbose:true adds raw matrices and transform components. Limitations: (1) boxes are resolved LAYER GEOMETRY, not painted pixels — shape bounds are conservative and can include transparent or animated branches; check a rendered frame (picsart_media_contact_sheet) when the visible extent matters. (2) On v3 text reports a real font-metric box; on jet text is not measured — the layer is listed (id, timing, hierarchy, zIndex, active) with no box/center/onCanvas and a notes[] entry, because the only box available for text there is a composition-sized placeholder, whose every number would look plausible and mean nothing. Any other degenerate box (a failed text measurement, collapsed auto-sized content) is flagged in notes[] too. (3) The query returns an inline report without saving a report file, and may fetch referenced scenes, fonts, and caption transcripts through guarded public-URL reads. (4) GEOMETRY ONLY, not a render/export gate: effects, assets, codecs and engine render support are not evaluated; only a pixel render proves visible output. Every report repeats these caveats in scope.
picsart_media_quickstart
ChatGPTCall FIRST when the user asks how to accomplish a media task (merge/concat videos, make a contact sheet, or export/render a scene). Returns ready-to-run picsart_media_* tool-call sequences. Omit recipe for the index.
picsart_media_reframe_video
ChatGPTWithout scene, replies with a media job receipt by default, not the reframed scene: pass the receipt's job object verbatim to the status tool named in its tools.jobStatus, which reports progress and, once the job finishes, the same result this tool returns with async:false. With scene + layer_id it always waits and replies with the reframed scene itself. Reframe a video to a different aspect ratio, tracking the subject with an animated pan/zoom rather than a fixed centered crop. Returns a scene ready to render with picsart_media_export — pass scene + layer_id to attach the reframe to an existing scene's layer instead of synthesizing a new one, e.g. after picsart_media_upload — that layer's media asset, content bounds/fit, and transform anchor are all normalized to (and, for the asset, reassigned to) url itself in the process, so the layer is guaranteed to show the exact video the crop track was computed against, noted in the response when anything actually changed. Inspect the result with picsart_media_validate_scene before exporting. It reframes by moving and scaling the existing footage; it never generates new pixels to fill a wider frame, so the output resolution is limited to what the source actually contains at the target aspect.
picsart_media_resolve_looks
ChatGPTExpand every by-reference look (each layer's looks[] annotation) in a scene into its concrete nested composition, returning a SELF-CONTAINED scene — the preset logic baked in, no look-catalog dependency at render time. The explicit, on-demand counterpart of the just-in-time resolution that picsart_media_translate_scene / picsart_media_contact_sheet / picsart_media_query_layout already do internally. Use it to 'flatten' a thin look-annotated scene into a portable one (e.g. to hand off, archive, or edit the expanded layers directly). Idempotent: a scene with no looks[] returns unchanged. With layerId, only THAT host's looks are flattened (a layer or a track clip, top-level or nested) — the surgical form for editing one look past what its params reach — and every other host stays by-reference; errors with look_host_not_found if nothing with that id carries looks, and with look_host_in_template if that host sits in a body that declares parameters (its looks expand when the template is instantiated). Pure: takes the full scene by value, returns a new scene.
picsart_media_screen_moments
ChatGPTFinds the moments in a screen recording that a promo can be cut from: what the recording is, what changed on screen, where and when, the stretches where nothing did, and the steps that change adds up to. Mechanism: reads the frames through ffmpeg jobs on the media platform (10 fps at 640 px by default; one job per three minutes or so, at most four, in parallel), measures frame-to-frame change, and groups it into events (cut, scroll, reveal, progressive), dead ranges (still, waiting) and proposed steps. One more job finds the subject of each large result: its textured part, which a promo pushes in on. No vision model is used. Returns one JSON: source, analysis, input (width, height, orientation, edited, cutsPerMinute, cuts, hasAudio), events, dead, content, work, bandCuts, tier (prompt_over_result, timelapse or recut) with tierReason, steps (each with subject when one was found), stepsNote and stagesHint when there are no steps to propose, and diagnostics. Look at a step's result with picsart_media_video_stills before trusting it. A long recording is read at a lower fps and width, and diagnostics.reduced says so. Charges credits on a hosted surface: every ffmpeg job is charged, up to five per call.
picsart_media_screen_stages
ChatGPTPicks the stages of a long screen session, the moments least like each other, for a timelapse. Mechanism: reads the recording at 2 fps as 48 px colour thumbnails through ffmpeg jobs on the media platform (one job per three minutes or so, at most four, in parallel), masks the pixels that are always moving (a camera inset, a clock), then picks, greedily, the thumbnail least like every stage picked so far. count stages in all, shared among chapters by length, at least 2 each. Returns the stage times with their novelty (mean RGB difference, 0-255), per chapter and in one list. Look at them with picsart_media_video_stills to name the chapters and find the reveal. An edited video's shots are chapters too: pass its cuts (picsart_media_screen_moments input.cuts) as chapters. Charges credits on a hosted surface: every ffmpeg job is charged, up to four per call.
picsart_media_segment_shots
ChatGPTSplits a window of a video into fragments, holds (the frame holds still) and transitions (it changes), each with a suggested sampling interval for measuring it. These are sampled visual changes, not scene labels. A request over the work limit is refused, never downsampled. Replies with a media job receipt by default, not the fragments: give its job object as is to the status tool its tools.jobStatus names; async:false waits for the fragments instead. Spends credits on every call.
picsart_media_track_motion
ChatGPTTracks objects or feature points through a window of a video and returns their motion as fitted scene animations, with dense per-frame samples at resultUrl. Replies with a media job receipt by default, not the tracks: pass its job object verbatim to the status tool named in its tools.jobStatus; async:false waits for the tracks in this call. It measures sampled pixels, not object identity, so check each target's coverage and uncertainty before using its animation. Each call is charged in credits.
picsart_media_track_motion_diff
ChatGPTCompares one tracked target across two trajectories from picsart_media_track_motion, reference a and candidate b, on one channel: b is resampled onto a's times. Returns maximum and mean deviation, the worst time and coverage, with per-sample deviations at resultUrl. No pixels are rendered. Replies with a media job receipt by default, not the deviations: hand its job object unchanged to the status tool in its tools.jobStatus; async:false returns the deviations directly. Charges credits per comparison.
picsart_media_transcribe
ChatGPTReplies with a media job receipt by default, not the transcript: pass the receipt's job object verbatim to the status tool named in its tools.jobStatus, which reports progress and, once the job finishes, the same transcript this tool returns with async:false. Set async:false to wait for the transcript in this call instead. Transcribe speech from an audio or video URL, with word-level timestamps and optional speaker diarization. Returns a transcript already shaped for a captions layer — pass it straight into picsart_media_patch_scene on a captions layer (content.transcript) to burn captions into a video via picsart_media_export, no reshaping needed. Also returns cutPoints: word-boundary-safe timestamps (sentence ends + silence gaps) useful for trimming without cutting mid-word. Word-level timings are omitted for a segment whose ASR alignment was incomplete rather than guessed at — check notes for which segments were affected. Not a general audio-understanding tool: it returns spoken words only, never a description of non-speech audio content or visual content — for the latter, use picsart_media_describe_video.
picsart_media_translate_scene
ChatGPTTranslate a scene into an engine's project format and return the complete project inline. A large scene's project can be ~100 KB of JSON; it is returned whole because a truncated project cannot be loaded. The target engine is chosen by engine (default v3 → a full, openable Replay file { meta, context:{layers,…}, actions, settings }; jet → a Jet project { compositions, activeCompositionID, ColorSpace }). Validate the scene first; the translator does not re-validate. Deterministic: identical (scene, engine) input returns an identical project.
picsart_media_upload
ChatGPTOpens a drag-and-drop upload widget so the user can get a local image/video/audio file into this conversation as a URL — no filesystem access on your side, and no external CLI needed. Call this whenever a user wants to use a local file with any picsart_media_* tool, or after a local-path argument was refused with a local_source_not_supported error. Call with no arguments to just open it. Optional purpose labels the dropzone; accept restricts file kind; detected_files is a BEST-EFFORT, MODEL-SUPPLIED label hint ONLY — e.g. filenames you can see attached in this conversation but have no other way to reach — the widget shows it purely as a suggestion ("Drop clip.mp4 here") and NEVER filters or rejects what the user actually drops, since this hint can be wrong or hallucinated; known_urls pre-selects URLs already produced earlier in this conversation, so the user can continue with them alongside anything they upload or pick from their Picsart Drive (the widget's "My Drive" tab, shown when their Drive is reachable). The upload happens directly from the user's browser — no bytes pass through this tool. Once the user finishes (or continues with pre-selected or Drive files), the widget reports the resulting URL(s) back into the conversation. This is a two-turn handshake: this call only OPENS the widget and returns no URL(s) itself — they arrive on the user's NEXT message, not in this call's result. Opening this widget performs no upload or save. After the user uploads a file, the widget also attempts to save it to their Picsart Drive; saving is best-effort and requires the connected account.
picsart_media_validate_scene
ChatGPTValidates a scene and returns a list of structured diagnostics. Use this whenever you've assembled or modified a scene, especially before rendering. Each diagnostic carries a JSON path, a stable machine-readable code, a human-readable message, and optional hints. A scene is considered valid when no diagnostic has severity error. A reference inside the scene that resolves nowhere is a diagnostic at its path. A scene string that is not an http(s) URL fails the call instead of returning diagnostics. The tool is pure: it takes the full scene in and returns diagnostics; if you keep editing, call again with the updated scene.
picsart_media_video_stills
ChatGPTShows chosen moments of a video as ONE image you can look at: a still at each of times (up to 20), optionally cropped to one box in source pixels, tiled into a single sheet. Mechanism: one ffmpeg job on the media platform seeks to each time and tiles the stills, 4 px apart, columns per row. The tiles carry no burned-in labels. Returns the sheet's URL, its size, and each tile's time and rect on it, so a tile maps back to its moment. Use it to check a proposed step's result from picsart_media_screen_moments, to name a timelapse's stages from picsart_media_screen_stages or find its reveal, or to confirm a subject. Times past the end are clamped to the last frame. Charges credits on a hosted surface: one ffmpeg job per call.
picsart_model_catalog
ChatGPTReturns the Picsart model catalog as plain data — renders NO widget or UI. Use it to choose the model for picsart_generate, answer catalog questions, and compare Picsart model capabilities. picsart_list_models shows the same catalog in the Studio widget. Same filters and result shape as picsart_list_models, but every item is rich by default: id, name, mode, inputType, purpose, provider, badges, description, plus supportedAspectRatios/supportedResolutions when the model declares an enum for that param — enough to answer "which models support 16:9" without picsart_model_params. Every item carries purpose: generate (makes a new asset from a prompt), edit (changes an existing asset of the same medium) or utility (a fixed transform of an input asset). Filter on purpose: "generate" whenever the user wants something made; results are sorted with generate models first. Inputs (all optional): mode (filter to image/video/audio/text — text = LLM models that return generated text), purpose (generate/edit/utility — see below; PASS generate for any "make me a…" ask), provider (case-insensitive substring like "flux", "kling", "google"), acceptsImage (true → only models that take an image input), acceptsVideo (true → only models that take a video input), acceptsAudio (true → only models that take an audio input), inputType (exact match on a model's input→output media code), limit (1–100, default 20), concise (default false; when true items carry only id/name/mode/inputType/purpose plus the ratio/resolution fields, to save tokens). Example: { mode: "audio", inputType: "music" } returns music-generation models. Returns { items, total, truncated } — truncated is true when more matched than were returned; refine filters or raise limit (max 100) to see more. Read-only; spends no credits and works without authentication.
picsart_model_choice
ChatGPTShows the user a Model Choice board for picking the model a later picsart_generate call uses: a short list of candidate models as cards, each with what it is best for and its key limits (max clip length, resolutions, aspect ratios, audio, cost note). The user taps one and their pick arrives as widget context; the board itself runs no model. Use it to present a project-specific shortlist when the user wants to choose among models with different duration, resolution, audio, or cost trade-offs. Candidate details can come from picsart_model_catalog. Pass 2 or 3 candidates (up to 4), describe each candidate's fit for the project in bestFor, and mark exactly one as recommended. The board returns the selected model id. Returns the normalised board payload the widget renders. Read-only; spends no credits and works without authentication. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool, if it has one, and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_model_choose
ChatGPTShows the user a Model Choice board for picking the model a later picsart_generate call uses: candidate models as cards, each with what it is best for and its key limits (max clip length, resolutions, aspect ratios, audio, cost note). The board runs no model. Pass 3 candidates (2 is fine; a 4th becomes a suggestion) with details from picsart_model_catalog, and mark exactly one recommended. A field beside the cards lets the user name any other catalog model in the same mode. One tap returns the selected model id, or the exact catalog id of a model named in the field. A model the user names that the board could not resolve: match it against picsart_model_catalog, and when the catalog does not offer it, open this board again with a fitting shortlist. The answer (model_choice_feedback) arrives on the user's next turn as widget context or in their message; read it before replying.
picsart_model_params
ChatGPTLists the settings one Picsart model supports in picsart_generate — a map of setting name to descriptor ({ type, required, default, enum, min, max, step, label, accept }) — so a picsart_generate call (its declared fields plus extra) uses only values that model accepts. Do NOT use it to discover which models exist (use picsart_list_models) or estimate cost (use picsart_preflight). Required input: model id. Example: { model: "flux-2-pro" }. Returns { model, schema: { <paramName>: { type: "string"|"number"|"boolean"|"file", required?, default?, enum?, min?, max?, step?, label?, accept? } } }. Read-only; spends no credits and works without authentication.
picsart_model_show
ChatGPTShows the Picsart model catalog, across ALL modes (image / video / audio / text), in the Picsart Studio model-picker widget so the USER can browse, compare, and pick the model for picsart_generate. Each item carries id, name, mode, inputType, purpose, supportedAspectRatios/supportedResolutions (when the model declares an enum for that param) (and provider, badges, description when verbose is true); purpose works as in picsart_model_catalog. Supports user-requested catalog browsing, cross-mode searches, and inspecting model forms. picsart_model_catalog returns catalog data without a widget; picsart_model_choose presents a shortlist of candidates for the user to choose from. Pass mode (image/video/audio/text) to show one output medium. Ratio/resolution constraints ride along in supportedAspectRatios/supportedResolutions, so you rarely need picsart_model_params just to check whether a model supports a given aspect ratio or resolution. Inputs (all optional): mode (filter to image/video/audio/text — text = LLM models that return generated text), purpose (generate/edit/utility, as its parameter says; PASS generate for any "make me a…" ask), provider (case-insensitive substring like "flux", "kling", "google"), acceptsImage (true → only models that take an image input), acceptsVideo (true → only models that take a video input), acceptsAudio (true → only models that take an audio input), inputType (exact match on a model's input→output media code), limit (1–100 per page, default 20), offset (default 0; pass the previous result's nextOffset to get the next page), verbose (default false; when true the text summary adds provider/badges/description per item — structuredContent always carries them). Example: { mode: "video", acceptsImage: true, limit: 10 } returns image-to-video models. Returns { items, total, truncated, offset, nextOffset }, paged as in picsart_model_catalog.
picsart_motion_setup
ChatGPTOpens the Picsart Motion Setup console for a motion-design video built from a storyboard of design frames (e.g. a Figma flow): output ratio (one of the five supported ratios — 9:16, 16:9, 1:1, 4:3, 3:4), fps (24/30/60), motion energy (calm/standard/energetic), the default seam and hold, and whether total length is DERIVED from the motion (the default) or targets a soft budget. The widget compiles the picks client-side and the user's decision comes back as a JSON message in the conversation (motion_setup_feedback: selections, summary, verdict locked). Call it once at the start of a motion-design project, prefilled: infer the ratio from the frames' aspect and the energy from the design and pass them in suggested so the console opens pre-selected for confirmation. Do NOT ask the running order (take the design's own) and do NOT ask a total duration (it derives from the motion). Store the returned selections as the project's output target (ratio -> width/height, fps) and as the seam/hold defaults; quote summary verbatim. Frame URLs must be Picsart-hosted: save frames from anywhere else with picsart_drive_upload first. Returns the normalised console payload the widget renders. Read-only; spends no credits and works without authentication.
picsart_preflight
ChatGPTChecks a planned picsart_generate request without running it: in ONE call it (1) validates the request's settings against what the selected model accepts, including the constraints between settings, and (2) attempts a best-effort credit estimate. Nothing is generated and nothing is charged. Use this after assembling params (user input, derived defaults, model swaps) and before generating, to surface bad arguments and show estimated cost when available. Do NOT use it to look up which params a model accepts (use picsart_model_params) or to actually generate (use picsart_generate). Required inputs: model id and params — the planned picsart_generate inputs (put the prompt inside params). Example: { model: "flux-2-pro", params: { prompt: "a cat in a hat", aspectRatio: "1:1", count: 1 } }. Returns { model, valid, errors?, credits }: valid/errors are from local validation (always present, no auth needed; errors only when invalid); credits is the dry-run cost (a number), or null when pricing is unavailable or the request is unauthenticated. It also probes every image input — every param the model declares as an image file (imageUrls, startFrame, endFrame, or a single imageUrl on an edit model): each Picsart-hosted picture's pixel size and bytes are read from its header, and a picture a video model would reject makes the call invalid with the fix in errors. The floor is 300 px on BOTH sides and the ceiling 6000 px on the long side, so a 252×508 panel cut off a character sheet is refused for its width just as a 480×270 contact-sheet thumbnail is refused for its height — the fix is to cut the panel again at a bigger scale, or to export the frame at full size with picsart_media_export (mediaType: "png", startTime). images[] lists what was found per picture, measured, whether or not it passed; warnings[] carries the soft findings (a picture over 4096 px, more than 15 MB of inputs in total). A startFrame/endFrame on a video model that also takes imageUrls is checked as a mode: mixed with reference media it is invalid on Seedance (the provider rejects the mix after the wait), and sent alone it earns a warning — only the people visible in that frame have a picture; put the frame first in imageUrls and say "IMAGE 1 — START FRAME" in the prompt to keep the references. A model-specific extra bag inside params is flattened before the checks.
picsart_prompt_verify
ChatGPTChecks a film prompt against the rules that are string matching or arithmetic, BEFORE you spend a credit on it. Read-only; spends nothing; refuses nothing — it returns a verdict table you and the user read. CALL THIS ON THE LITERAL ARGUMENTS you are about to pass to picsart_generate, every time, for a video run, a scene picture, a reference sheet, a room map or an edit. It reports: the house lines this KIND of artifact must carry, present word for word rather than paraphrased, and the ones it must NOT carry; the head count against the approved cast; the cut list against the shots; the approved line reproduced exactly and in order; each speaker's saved voice reproduced in full; whether a spoken line fits the seconds on its card; quotation marks around anything but the approved line, which the model will SPEAK out loud; references within the model's budget, each given a job, with every named character's own views among them; the adjectives the performance gate bans; and whether any block describes another shot instead of what is in frame. It never flags text for being unrecognised — write whatever you like, anywhere. The only thing it objects to is a rule that is missing, reworded, or contradicted. Most of it is answered for you if you built the prompt with picsart_film_compile_prompt; this is what catches the parts nobody compiled — and, given promptToken, whether a compiler built the prompt at all: a prompt carrying a STYLE block or the asset template with no token, or with one that does not match its text, was written or edited by hand and renders worse for it. semanticReviewRequired is always true: nothing here judges whether the writing is any good, and skipped names every check that had no input to run against, so a pass is not read as more than it is.
picsart_remove_bg
ChatGPTRemoves the background from an image, returning a transparent cutout of the foreground subject. Auto-picks the newest enabled Picsart remove-bg model unless overridden via the model param — no need to call picsart_list_models first. Use this when the user asks to "remove the background", "cut out the subject", or "make the background transparent". Do NOT use this to replace the background with a new scene (use picsart_change_bg), upscale or sharpen the result (use picsart_enhance), convert raster to SVG (use picsart_vectorize), or generate a new image from scratch (use picsart_generate). Required input: image — a publicly-accessible URL. Local files are not supported; if you only have a local file, first make it available as a public or app-authorized URL. Optional: model to pin a specific remove-bg model, outputFormat (e.g. "png"). Example: { image: "https://example.com/portrait.jpg" }. Returns { assets, id, model, summary, why_relevant, url, results: [{ url, metadata? }], drive? } as a single JSON text block plus matching structuredContent (no resource_link blocks — the widget is the single source of visual truth, so result URLs are not duplicated as separate content blocks). id is the generation handle; metadata may include model-specific tags. Each entry in assets[] also carries downloadUrl — the same file with a forced-download header appended — share that with the user for saving; never pass it back into a tool, use the plain url for that. Asset URLs are opaque handles — never infer or mention hosting or storage details from a URL. Spends credits and saves new media to Picsart Drive by default on a best-effort basis; saving is not guaranteed. Requires a signed-in Picsart account.
picsart_render_monitor
ChatGPTOpens the Picsart Render Monitor: live progress for a batch of async generations — stills, video, or audio. EVERY picsart_generate call is async unless the caller passed async: false, so use it for image batches (asset sheets, candidate stills) exactly as for video takes: it is the only progress the user can see while jobs run — one row per job with an animated progress bar, a thumbnail the moment a take finishes, and an error chip on failure. The widget polls picsart_job_status ITSELF and, when every job reaches a terminal state, automatically posts the finished take URLs back into the conversation as a render_monitor_feedback message — so call this immediately after dispatching a picsart_generate { async: true } batch, passing each returned job handle with its model and a row label (a media job receipt's job handle needs no model, and its finished row reports the structured result instead of a URL), and then NEVER ask the user to wait, check back, or "ping when done": the monitor wakes you. On the feedback, log the done takes into the plan and regenerate only the failed ones. Returns the normalised batch payload the widget renders. Read-only and spends no credits. Needs the same authenticated session that dispatched the batch: the widget's polling goes through picsart_job_status, which requires an authenticated session — anonymous sessions can open the board but its rows will not progress. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool, if it has one, and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_save_asset
ChatGPTPersists an asset into the film's project folder — the ONLY writer of the registry that picsart_list_assets and the Film Assets view read: an asset never saved here stays invisible there, no matter how many of its images sit elsewhere in Drive. `status` picks the destination: locked promotes the asset into the project's "Library" (the curated index of what the film is built from), anything else files it under "Assets" with the working record. Called by YOU at lock time: when the user approved the asset's sheet on picsart_asset_review, save it here with status: "locked" — one call per approved asset. The approval is the evidence the lock needs. portraitUrl is the asset's one gridded sheet — every angle and state in one image; turnaroundUrl is an optional second sheet. It creates (or reuses) the destination folder, adds a per-asset subfolder, and saves the sheet (carrying the manifest in attributes) plus the optional second sheet and voice sample. READ locked IN THE RESULT, NEVER saved, before telling the user an asset is done: a draft/review save is filed, versioned and durable but NOT locked, and it comes back with locked: false plus a remaining list naming what is left. Returns { saved, assetId, status, locked, remaining?, folder, portraitUid, voiceUid?, manifest, message }. Writes to Picsart Drive; requires a signed-in Picsart account.
picsart_scene_apply_gradient
ChatGPTInserts a validated gradient paint into an EXISTING shape layer that already has top-level geometry (rect/ellipse/path/polystar): a gradientFill, or a gradientStroke with width, placed after the geometry it paints. stops (>=2) are opaque colors (#rrggbb or color(<space> r g b)); transparency is the independent alphaStops ramp. type is linear (default) or radial; startPoint/endPoint are the axis in content-local px (endPoint is the radial radius reference); highlightLength/highlightAngle shape a radial highlight. Re-applying REPLACES the shape's same-family paint (fill/gradientFill, or stroke/gradientStroke) in place. Ramps are static; endpoints animate through the shape-item keyframe channel. Patterns (gradient text, washes, sweeps): the "scene-gradients" recipe (picsart_scene_recipe).
picsart_scene_apply_preset
ChatGPTApply one named preset to one layer of a scene and return the edited scene. Pure: takes the scene by value and keeps no state. preset is <catalog>:<id>, the catalog part saying where picsart_scene_capabilities lists it: effect:<id> (effects), motionPreset:<id> (motionPresets), textAnimation:<name> (textAnimations) or look:<id> (looksCompact, or picsart_scene_looks), e.g. effect:gaussian_blur, motionPreset:ken_burns, textAnimation:typewriter, look:vintage_bw. Read the preset's params there first: param names belong to their preset (gaussian_blur takes blur, not radius), omitted ones take the catalog defaults, and an unknown id or param is refused with what the preset accepts. A preset applies only to the content kinds in its appliesTo; layerId resolves at any depth, a track clip included, and only a camera preset may omit it to move the root composition's camera. An effect merges into the layer's effects[] (re-applying its id replaces it); a motion preset or text animation is baked as editable keyframes, a text animation from the layer's local time 0. A look is added to looks[] as a named, swappable entry by default; mode "expand" bakes it now. How each kind lands, masks and look baking: the "scene-animation-reference" recipe (picsart_scene_recipe).
picsart_scene_apply_template
ChatGPTInstantiate a scene template or authored starter with supplied parameter bindings. Read supportedModes first, from picsart_scene_capabilities with sections ["template:<uri>"]: expand-only starters refuse reference mode (including the default); choose bootstrap or inline explicitly. Three modes: reference (DEFAULT for reusable templates) packages a scene_ref content snippet (bindings + optional speed/trim/fit) for a parent layer; it renders as its OWN nested composition (its size and duration kept, fit/transform honoured). A reusable catalog template needs no declaration in the parent. bootstrap returns a complete resolved standalone scene (substitutes every $eval, synthesizes asset entries for asset-typed parameters, strips the parameters declaration) — an editable starting scene. inline MERGES the template's resolved layers + assets INTO a target scene you pass (no scene_ref) and returns it (ids prefixed, starts offset by at). A template of the target's own size and clock (fps, motionBlurSampleCount), without its own composition background, joins the target's stack flat; any other comes in as ONE inline composition layer of the template's size and clock (id: the prefix, starting at at, its layers at their own times inside), which the target fits (fit, default contain) and centres exactly as it fits a scene_ref to that template. The template's own assets come in under prefixed ids, assetId refs rewired; a target asset or composition BOUND into it arrives as a copy of that declaration, never its id (content.asset for a clip, a prefixed entry for an asset_* parameter). The target's own assets stay as written. Zero parameters is valid; customize expanded layers directly. Returns either sceneRef or scene plus appliedParameters: in reference mode exactly the bindings the snippet carries (unbound parameters take template defaults), in bootstrap and inline every value the resolve applied. In bootstrap mode, mpscene://montage takes an unset width and height from its largest video clip and its frame rate from its clips, and the result names which values came from them. For the common video job — concatenating/merging N clips with per-clip trim and fit/align into one output — read the quick-merge-and-export recipe with picsart_scene_recipe FIRST. It holds a complete, validated parameters payload for mpscene://montage, so that case needs no template or schema lookup.
picsart_scene_capabilities
ChatGPTReturns the scene-authoring reference: the capabilities document (layer content kinds, animatable properties, the effect, transition, look, motion-preset and text-animation catalogs with their params, per-feature format notes, and limits, the sizes the pipeline is exercised at, none of them enforced), the scene document's JSON Schema, and each scene template's description. Every call is this same read; sections picks what it returns, and omitting it returns the INDEX: every section name, the document's current size and how to ask for the large sections. Free, read-only and safe to cache.
picsart_scene_check_contracts
ChatGPTChecks named, time-scoped relationships between a scene's layers against the scene, without rendering: component lifetimes, containment, fixed or attached edges, shared travel, matching fades, order along depth, x or y, absolute motion limits (motion_range) and cross-time handoffs. Use it when relationships change over time, or to replay design-intent checks after an edit; declare the contracts from the design, not by copying tracks that may be wrong. Pass the document as contracts, or a reusable template with targets, numbers and an optional clock: the template is resolved to a document first (every binding must exist and be used), and that document comes back as resolved beside the verdict, ready to pass as contracts next time. It does not solve layout, measure occlusion or infer semantic identity. Returns pass, fail or inconclusive per contract with exact sample times and failure evidence; a sample outside the scene is inconclusive, never clipped. At most 64 contracts and 1000 sample times. The recipe "linked-element-motion" (picsart_scene_recipe) covers authoring.
picsart_scene_check_motion
ChatGPTAnalyze scene motion directly at EVERY output frame in an explicit root-time window and FPS, without rendering. Checks value_range, signed velocity_range and acceleration_range for root-box centers, unrotated sizes, rotation or effectiveOpacity. Detect reversals, jumps, overshoot and unsettled tails using limits chosen from design intent. Returns status, per-check extrema/units, frame-interval evidence and exact coverage. This is frame-complete finite-difference analysis, NOT mathematical continuous-time/sub-frame proof or pixel-quality assurance. Rotation rates use shortest turns; half-turn ambiguity, missing targets and insufficient consecutive frames are inconclusive. Geometry quantization affects rates. At most 1000 frames/64 checks; split longer ranges with 1-frame overlap for velocity or 2 for acceleration. Never lowers FPS silently. Use actual export FPS and read status, not just tool success. Use picsart_scene_recipe with name "scene-animation-reference" and reference "references/frame-motion-validation.md" for the frame-validation guide.
picsart_scene_contact_sheet
ChatGPTRenders low-res jpeg thumbnails of an authored scene and tiles them in time order into ONE sheet image you can look at: { frames: [{time, url}], sheet: {columns, rows, tiles: [{time, x, y, width, height}]} }. Pass times (preferred; at most 8, more are thinned evenly) or frames (default 8, up to 24, evenly spaced on the sampling frame grid). Every frame is a real render. If the sheet cannot be drawn, sheet is null with the reason and the frame urls are still complete: open them rather than calling again. Sources must be reachable public http(s) URLs; validate the scene first. Not a metadata probe: a source clip's duration and size come from picsart_media_probe, and layer geometry without rendering from picsart_scene_query_layout.
picsart_scene_diff_layouts
ChatGPTDiffs the resolved layout of two scenes (two boards), each at one time (timeA/timeB, default 0), and reports per layer WHAT CHANGED: moved, resized, restyled, content-changed or unchanged, or entered (B only) / exited (A only). Each matched layer carries matchedBy and a delta { dPos, travelPx, dScale, dScaleXY, dRotation, dZ, visibilityChanged, contentChanged } in root-space pixels. The whole pair gets a relationship, shared-layers, zoom-detail, in-place-emphasis, unrelated or indeterminate (no comparison was possible, not a difference), which routes smart-animate vs camera vs cut. Pass matchHints to pair layers whose content and ids differ. Geometry only and read-only: turn deltas into motion with picsart_scene_patch / picsart_scene_apply_preset. CAN BE UNAVAILABLE: it resolves both scenes through picsart_scene_query_layout and fails whenever that tool is unavailable. Matching rules and text caveats: the "motion-scene-continuity" recipe (picsart_scene_recipe).
picsart_scene_editor
ChatGPTOpens the Picsart scene editor on a scene document: the document PLAYED in the user's browser exactly as authored, over a clip timeline with the editing toolbar — trim, split, delete, duplicate, adjust, speed, effects, volume, resize — and one send button, labelled Submit once they edit or comment and Accept until then. Pass the document itself as scene — the parsed object, never a URL or a string. The document opens directly, exactly as authored: masks, per-keyframe easing, corner radii, vector art and real glyph layout render as the format specifies. Expand any scene_ref layer before opening (picsart_media_expand_scene_ref, or picsart_media_apply_scene_template mode bootstrap) — the editor resolves assets[] and track layers itself, but not a template reference. IT IS FREE AND RENDERS NOTHING: edits are applied to the document in the browser; no file is produced and no credits are spent. When the user sends it back, the reply carries verdict ("approved": they pressed Accept without editing or commenting, so move on with the scene as it is; "needs_changes": they pressed Submit after editing or commenting), edited (whether they committed any edit), document — the scene AS THEY LEFT IT, which supersedes the one you opened when edited is true — comments (pins on the picture, each with its own instruction and the moment it is about), timelineComments (marked stretches of the timeline, each with its own text and its start/end seconds), and duration, the length the editor resolved. Either comment set may be absent; both absent on "needs_changes" means they edited it without saying anything more, so treat document as their answer. There is NO videoUrl: nothing was rendered, so do not look for a file, do not claim one was saved, and do not save anything to Drive on the strength of this reply. Render document with picsart_media_export when they want a file; apply further changes to document with picsart_media_patch_scene, then open the editor again on the result. Before opening, each clip is checked and, where its encoding would make the editor stall on seeks, a playback copy is prepared; the reply's playback map (original URL -> copy) is for the widget alone. The document keeps its original URLs, and the document sent back names only originals, so nothing downstream changes. Returns the normalised payload the widget renders. Read-only; spends no credits and works without authentication. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_scene_expand_ref
ChatGPTDETACHES a scene_ref into editable layers, one level per call: the ref named by layerId, or every resolvable top-level ref without it. A plain ref (only id, start, duration and its reference; the host's size, frame rate and sample count; no longer than its scene; every child starting inside its window) detaches FLAT: its layers join the parent stack as <refId>__<childId>, offset by the ref's start. Any other ref stays the same layer, its content an inline composition of the scene's layers. A scene composition.background becomes a bottom __background layer, and scene assets come in under prefixed ids. stillReferenced lists every reference left. An invalid read refuses with invalid_scene, and so does a remote scene that cannot be fetched; any other unresolvable ref is left as-is in bulk and is an error with layerId. How bound assets and compositions come across: the "picsart-video-rules" recipe (picsart_scene_recipe).
picsart_scene_export
ChatGPTRenders a fully-authored scene to a final file on Picsart's servers and returns its urls: an MP4 by default, or the mediaType you pass (png with startTime for one still). Free. Replies with a media job receipt by default: pass its job verbatim to the status tool named in tools.jobStatus, which returns the same result once the render finishes; async:false waits for the result instead. Only a completed inline export is saved to Picsart Drive automatically, best effort: report a save only when driveUid comes back; an async result is saved only when you pass its URL to picsart_drive_upload, with folderUid for a folder. Scene sources must be public http(s) URLs. Validate the scene with picsart_scene_validate and look at a frame with picsart_scene_contact_sheet before exporting; with no scene yet, start from the "quick-merge-and-export" recipe (picsart_scene_recipe). Give the user the downloadUrls entry to save a file; pass tools the matching urls entry.
picsart_scene_fonts
ChatGPTFinds fonts for text layers: the built-in catalog, plus (on page 1) a live search of Picsart's font catalog, in-house faces and Google Fonts. Use this before authoring any text layer so font.family resolves to a real font. The renderer has no system-font fallback -- passing CSS family names like Inter, Arial, or Helvetica produces empty text and a unknown_font_family validation error. fonts is the built-in catalog, paged: at most pageSize entries (default 50, max 200) plus total, page, pageSize and hasNext -- pass page to read on. Each has a stable key, passable directly as a text layer's font.family, and a resolved .otf/.ttf URL. live.fonts holds the faces the live search found that the catalog does not already list: each carries a ready-made asset -- add it to the scene's assets[] with an id and put that id in font.family (an entry that also has a key can use the key instead). live.status is unavailable when the search failed; the catalog page still stands. No face is listed twice, within or across the two lists. Every entry has a source (catalog, picsart or google) and may carry a licenseType (commercial or personal) for usage-rights filtering. Live entries also carry paid (a Picsart subscription face); those are listed only to a signed-in caller -- for an anonymous one they are left out of live.fonts, and live.paidHidden is true when any were. Built-in catalog entries carry no paid flag and are listed to every caller: their licenseType is the usage-rights signal. Agents may also pass a direct font URL matching accepted_url_pattern. Narrow with query (substring of key or display name), family (e.g. "Roboto" for all its variants) and licenseType instead of paging through the whole catalog.
picsart_scene_import_figma_paint
ChatGPTConvert a Figma element into scene items instead of baking it to an opaque SVG or PNG that cannot animate, scale or recolor. This tool accepts CSS paint for an existing layer. CSS paint (fill, boxShadow, gradient from the design file the user shared) converts paint onto an EXISTING shape layer: fill becomes a shape fill (a shape paint's color is RGB-only, so any alpha is stored in the fill item's opacity); boxShadow becomes a drop_shadow effect (an INSET one is skipped: no inner-shadow primitive); gradient becomes a gradientFill (or gradientStroke) and needs the element size [w,h] because CSS carries only an angle. Gradients are resampled to Figma's blend using the default color profile. Returns the updated scene, applied (what was created), and skipped ({what, reason}) so nothing is dropped silently.
picsart_scene_import_model
ChatGPTImports a 3D model (GLB, glTF or binary FBX) from a public https URL and returns it as one uncompressed GLB, with a report of its nodes, bones, morph targets, materials and animation clips and the parameters proposed to drive it. Replies with a media job receipt by default, not the model: pass its job object verbatim to the status tool named in its tools.jobStatus; async:false waits for the model in this call. expose picks which parameter kinds to propose (bones, morphs, materials, clips): by default all of them, except a bone an animation clip already turns, which is proposed only when bones is named. expose: [] is a plain conversion. face separates a face region and returns its details in report.face. Draco and meshopt compressed input is accepted. Limits: 64 MB, 2M triangles and a URL of up to 4096 characters; a glTF must embed its buffers and images as data: URIs; KHR_texture_basisu textures and .blend files are refused. Use it before picsart_scene_preview_model for a glTF, an FBX or a compressed GLB. The GLB link is temporary and is not saved to Drive.
picsart_scene_import_svg_path
ChatGPTConvert an SVG path-data string (the d attribute) into editable path items on a shape layer, instead of an opaque SVG asset that cannot animate, scale or recolor. Pure. Parses the full SVG path grammar, absolute and relative, curves and arcs included; each subpath becomes one path item, and unparseable data fails with invalid_path_data rather than wrong geometry. Pass color (with fillRule "evenodd" when the SVG sets it) and/or stroke + width to paint it: the paths and their paint are appended as ONE group, so the paint never reaches the layer's other shapes; with neither, the bare paths are appended. For a gradient, import geometry only onto a dedicated shape layer, then call picsart_scene_apply_gradient on it. Transparency goes in fillOpacity / strokeOpacity; a color carries no alpha. Returns the updated scene, applied (the item types created) and skipped ({what, reason}) for any subpath with no drawable outline.
picsart_scene_inspect
ChatGPTRead a large scene without returning the whole document. Read-only. outline (default) pages the authored layers (inline compositions, track clips and masks included), then the scope's assets: 20 entries by default, at most 100; continue with nextOffset and the same selection. Rows carry local timing as written, parentId, animated property names, depth fields and the patch-compatible address. read returns one exact entity or relative field path, addressed as picsart_scene_patch addresses it. layer selects a subtree (outline) or entity (read); scope selects an embedded scene asset, not an inline composition. It does not evaluate expressions or root timing, validate, or fetch nested references. A response over 24000 UTF-8 bytes is refused, never truncated: lower limit or narrow path. Pass the returned sceneSha256 as ifSceneSha256 to refuse a changed scene; it is not a patch precondition. Read ok/error in the result, not only call success. Large-scene authoring: the "large-scene-assembly" recipe (picsart_scene_recipe).
picsart_scene_lint_layout
ChatGPTChecks a scene's layout over a time window without rendering: samples picsart_scene_query_layout, checks any declared relationships (detached labels, outgrown panels, a stack read front to back) and classifies every overlapping pair of on-canvas layers in the same composition as intentional, transient, a graze or a collision finding. Also lists text left mostly hidden under opaque layers (covered) and root layers mostly off canvas (mostlyOffCanvas). Use it for overlaps and relationships across time; picsart_scene_query_layout reads one moment. Free and read-only. A lint, not a gate: findings never fail the call; bad options, windows and query errors do. Pass intended overlaps in allow. At most 600 samples per call: a window that needs more, at the default step or an explicit one, is refused with the smallest step that fits. How to read the report: the "linked-element-motion" recipe (picsart_scene_recipe).
picsart_scene_looks
ChatGPTDiscover looks without loading the whole catalog. Start with facetsOnly:true for global categories, behavioral tags and supported content kinds, then filter by exact category, all-of tags and appliesTo (combined with AND). Returns compact look rows with parameter ranges/defaults plus global facets, even on empty matches. Existing tags in/out/loop/static/animated describe timing behavior, not visual subjects; category names primary purpose such as ui_widget, framing or motion. Unknown values match nothing. Omit filters for all. Inspect one full definition via picsart_scene_capabilities sections:["look:<id>"] before applying it as a look:<id> preset with picsart_scene_apply_preset; use picsart_scene_resolve_looks for deeper edits. Looks have no scene-template referencePolicy filter.
picsart_scene_patch
ChatGPTEdits a scene with 1-64 ID-anchored ops, applied in order to one clone and atomically: the first failing op aborts the batch with a typed error (code, opIndex), and the input is never mutated. Returns the patched scene inline as scene and summary.ops (each op's resolved pointer, plus notes when it did more). Verbs: set (create-or-replace; replace is an alias), remove, add, and the timeline verbs wrap, shift, copyAnimation, hardCut (see ops). Address with exactly one anchor + id, layer or asset (a sound is a layer, content.kind:"audio"); a root index path such as layers/3/... is refused with use_id_anchor. add with kind and the whole entity as value creates a new layer or asset; an anchored add with path inserts into that entity's array. Omit the anchor for whole-entity adds, composition/* and version. path is a slash-separated RFC-6901 pointer relative to the anchor (content/text, effects/0/params/amount). A sub-scene is an asset (type:"scene"), edited inside with scope. The result is fully validated: an error the patch introduces fails the batch, one the input already held returns valid:false, and valid:true needs no picsart_scene_validate after it. Validation does not fetch remote assets or scene_refs.
picsart_scene_preview_model
ChatGPTRenders a GLB model to a still PNG or a turntable MP4 (mode), at size pixels (128-1024, even), with frames for a turntable (8-120), camera yaw and pitch in degrees and a background color. Replies with a media job receipt by default, not the preview: pass its job object verbatim to the status tool named in its tools.jobStatus; async:false waits for the preview in this call. It takes an uncompressed GLB only: import a glTF, an FBX or a Draco or meshopt GLB with picsart_scene_import_model first and preview that output. The preview link is temporary.
picsart_scene_query_layout
ChatGPTResolves a scene's layers at one root-time moment without rendering. Free and read-only. Per layer: top-left-pixel box, center, rotationDeg, zIndex (paint order at that time), visible/active, onCanvas, timing, hierarchy, and evaluated opacity/effectiveOpacity where available (absent means unavailable, not opaque). Each id is a picsart_scene_patch layer address; nested children are namespaced host__child; internal:true layers are implementation. Inactive layers have active:false and no box. A layer drawn through a perspective camera reports quad (four projected corners), depth (eye distance px, larger is farther) and no rotationDeg. verbose:true adds matrices and transform components. Bounds are layer geometry, not painted pixels, and this is not a render/export gate. It reads one moment; overlaps and relationships over time are picsart_scene_lint_layout. When layout resolution is unavailable, inspect rendered pixels with picsart_scene_contact_sheet; do not substitute guessed geometry. Engine differences and reading the report: the "linked-element-motion" recipe (picsart_scene_recipe).
picsart_scene_recipe
ChatGPTReads the recipe catalog: authoring guides written for this toolset (skill-format markdown, e.g. how to merge clips into one video, or turn a Figma storyboard into an animated scene). Every call is this same read; name and reference narrow it. Omit name for the INDEX, { recipes }: each recipe's name, description and any category/version, with no body, small enough to read in full before choosing. Pass name for that recipe's full markdown body plus referenceFiles, the companion files it links to (e.g. references/motion-rules.md): { name, description, metadata?, body, referenceFiles }. Add reference (one of those paths) to get { name, reference, content }, that file's raw content INSTEAD of the body, so detail is pulled only when it is needed.
picsart_scene_resolve_looks
ChatGPTExpand every by-reference look (each layer's looks[] annotation) in a scene into its concrete nested composition, returning a SELF-CONTAINED scene — the preset logic baked in, no look-catalog dependency at render time. The explicit, on-demand counterpart of the just-in-time resolution that picsart_scene_translate / picsart_scene_contact_sheet / picsart_scene_query_layout already do internally. Use it to 'flatten' a thin look-annotated scene into a portable one (e.g. to hand off, archive, or edit the expanded layers directly). Idempotent: a scene with no looks[] returns unchanged. With layerId, only THAT host's looks are flattened (a layer or a track clip, top-level or nested) — the surgical form for editing one look past what its params reach — and every other host stays by-reference; errors with look_host_not_found if nothing with that id carries looks, and with look_host_in_template if that host sits in a body that declares parameters (its looks expand when the template is instantiated). Pure: takes the full scene by value, returns a new scene.
picsart_scene_templates
ChatGPTDiscover scene templates and authored starters with optional exact category, all-of tags and referencePolicy filters (combined with AND). No filters lists all. Brief rows omit descriptions; detail:"full" returns them, best with a category or tags filter. Returns templates and global facets (categories, tags, referencePolicies), even on empty matches. Use facets to discover vocabulary and broaden filters. UI elements: ui_widget; data/diagrams: infographic; editorial stories: editorial. reusable selects entries allowing catalog references (no expand-only flag); expand-only requires bootstrap/inline. Read supportedModes; zero parameters means edit expanded layers. Not semantic search. Use facetsOnly:true for cheap initial vocabulary discovery without template descriptions; it returns templates:[] and global facets, independent of row filters.
picsart_scene_translate
ChatGPTTranslate a scene into an engine's project format and return the complete project inline. A large scene's project can be ~100 KB of JSON; it is returned whole because a truncated project cannot be loaded. The target engine is chosen by engine (default v3 → a full, openable Replay file { meta, context:{layers,…}, actions, settings }; jet → a Jet project { compositions, activeCompositionID, ColorSpace }). Validate the scene first; the translator does not re-validate. Deterministic: identical (scene, engine) input returns an identical project.
picsart_scene_validate
ChatGPTValidates a scene and returns a list of structured diagnostics. Use this whenever you've assembled or modified a scene, especially before rendering. Each diagnostic carries a JSON path, a stable machine-readable code, a human-readable message, and optional hints. A scene is considered valid when no diagnostic has severity error. Validity is target-free: a valid scene a target's translator cannot represent (a rotation over a non-uniform scale, an authored component anchor, …) stays valid, with each translator's refusal as an engine_cannot_represent warning at / and a hint naming what that target can do; picsart_scene_translate, picsart_scene_query_layout and picsart_scene_export refuse it on that target. A reference inside the scene that resolves nowhere is a diagnostic at its path. A scene string that is not an http(s) URL fails the call instead of returning diagnostics. The tool is pure: it takes the full scene in and returns diagnostics; if you keep editing, call again with the updated scene. A root scene URL is fetched through guarded public-URL reads. Validation does not fetch nested remote scene references; translation and layout queries resolve those references.
picsart_settings_read
ChatGPTReturns the signed-in user's Picsart display settings: how Drive files are arranged and whether video previews play automatically, with the schema that describes them. Takes no input.
picsart_settings_update
ChatGPTChanges the signed-in user's Picsart display settings. set holds at least one of driveLayout (grid or list) and autoplayVideo (true or false); settings left out keep their value. Returns every setting after the change as { values }. Costs no credits.
picsart_shotlist_board
ChatGPTOpens the Picsart Shotlist Board: the scene's shots as editable cards, story first. Each card shows what happens and what is said as text areas the user types straight into, then seven decisions as pills that open a picture rather than a list — shot size drawn as a figure inside the frame, camera move as arrows around it, lens as its focal length in millimetres, aperture as an f-stop, light and colour as the real thing, and length. Colour offers exactly the seventeen film-setup palette presets with the same generated stills, so a palette means one thing across both surfaces. Cards reorder, duplicate, cut (reversibly) and reset; a card can be added. The user's approval comes back as a JSON message in the conversation (shotlist_board_feedback: scope, verdict "approved", and per scene the FINAL shot list in order with every shot's values — replace your stored shotlist with it rather than merging). Call it once per planning pass with every scene in one call. picsart_film_setup MUST HAVE RUN FIRST — this board's lens, light and colour pills are that console's own presets, so opening this one first asks the user for choices from a vocabulary the film has not adopted yet. This board is also where shot length and camera move live for real: the film setup console offers neither, and the length control here offers exactly the durations the chosen model accepts, so a card cannot hold a duration the model will refuse. This board plans; it does not review generated takes — a take is judged in picsart_scene_editor, the Editor. Returns the normalised board payload the widget renders. Read-only; spends no credits and works without authentication. HOW THE DECISION ARRIVES: when the user presses the board's button, their decision is delivered as WIDGET CONTEXT, not inside their chat message — the chat shows only a one-line user sentence announcing it. On that turn, BEFORE replying, read the widget context: call the host's widget-context tool, if it has one, and act on its result; where a host attaches the context to the turn instead, read that. Only when both are empty may you say the payload is missing. Never ask the user to repeat, describe, press again or paste it.
picsart_social_accounts
ChatGPTLists the user's social accounts connected for posting from Picsart: for each, the platform (for example instagram, tiktok, youtube, or twitter for X), the account id, the username and whether it can post right now. Call it before offering to share a result on social media, to know which platforms are ready. A platform missing from the list is not connected; canPost: false means it must be reconnected with picsart_social_connect. Read-only; changes nothing and spends no credits.
picsart_social_connect
ChatGPTShows the user a Connect panel for the social platforms named in platforms: one row per platform, showing the connected account, a button to connect it for posting, or a button to reconnect it. The user signs in to the platform in a new browser tab, and the panel confirms the connection when they come back. Use it when picsart_social_accounts shows that a platform the user wants to post to is missing or cannot post. The panel connects accounts; it posts nothing. Returns one row per platform with its state.
picsart_social_connect_link
ChatGPTReturns the sign-in link that connects one social platform account for posting, for the Connect panel to open in a new tab. Called by the panel's Connect button. Returns { authUrl }, or { alreadyConnected: true } when an account for that platform is already connected.
picsart_social_disconnect
ChatGPTDisconnects one social account from posting through Picsart. Called by the Connect panel's Reconnect button just before the account is connected again. The account itself and its posts are not affected.
picsart_social_post_preview
ChatGPTShows the user a Post preview for sharing Picsart media on their social accounts: the images or video, an editable caption, every platform the user can post to with the ones in platforms ticked, and Schedule and Post now buttons. This call posts nothing: the post goes out only when the user presses Post now or Schedule in the preview, once each ticked platform's required settings are filled in there. Pass the media URLs exactly as Picsart returned them and a caption you wrote for the post. A platform that is not connected shows a connect button in the preview. The result for each platform, with a link to the live post when there is one, arrives when the user acts. Returns the draft the preview renders.
picsart_social_post_status
ChatGPTReturns the current status of a post made from the Post preview: by its post id when known, otherwise by finding it among the account's posts made since it was submitted. Called by the preview while a post is still processing. Read-only; never posts.
picsart_social_publish
ChatGPTPosts, or schedules, one post of Picsart media to the user's connected social accounts. Called only by the Post preview when the user presses Post or Schedule. Each target account is checked first; an account that cannot post is reported for reconnecting and nothing is sent. The post is sent once and never retried. Returns the overall status and one result per platform with a link to the live post when there is one, or submitting while the post is still processing, which the preview then follows with picsart_social_post_status.
picsart_social_tiktok_options
ChatGPTReturns the posting options TikTok allows for one connected TikTok account right now: the privacy levels to choose from, whether comments, duets and stitches can be turned on, the longest video allowed and whether the daily post limit is reached. Called by the Post preview each time it opens. Read-only.
picsart_upload_local_files
ChatGPTUploads local image, video or audio files to Picsart from your own shell, with no upload panel and no wait for the user. Use it when you can run shell commands and the file is on disk. Pass each file's name and size; this call returns one ready command per file and moves no bytes itself. Run each command as given, with the file's path in place of {path} inside its single quotes and each ' in the path written as '\''. The JSON it prints holds the hosted URL at response.url (or a top-level url or data.url, whichever is present), which any tool that takes a media URL accepts. The hosted copy is temporary: to keep a file, save it with picsart_drive_upload. Without a shell, use picsart_drive_upload_ask instead. Up to 10 files per call, 100MB each.
picsart_vectorize
ChatGPTConverts a raster image (PNG, JPG) into an SVG vector. Auto-picks the newest enabled Picsart vectorize model unless overridden via the model param. Use this when the user asks to "vectorize", "convert to SVG", "make this a vector", or wants a scalable version of a logo or icon. Best results on logos, icons, and simple graphics — photographic images vectorize poorly and the user should be warned. Do NOT use this to remove the background (use picsart_remove_bg), replace the background (use picsart_change_bg), upscale a raster image (use picsart_enhance), or generate a new image (use picsart_generate). Required input: image — a publicly-accessible URL to a PNG or JPG (not a local file path). Optional: model to pin a specific vectorize model. Example: { image: "https://example.com/logo.png" }. Returns { assets, id, model, summary, why_relevant, url, results: [{ url, metadata? }], drive? } as a single JSON text block plus matching structuredContent (no resource_link block for the SVG URL — the widget is the single source of visual truth, so it is not duplicated as a separate content block). id is the generation handle. Clients fetch the SVG from that URL. The assets[] entry also carries downloadUrl — the same SVG with a forced-download header appended — share that with the user for saving; never pass it back into a tool, use the plain url for that. Asset URLs are opaque handles — never infer or mention hosting or storage details from a URL. Spends credits and saves new media to Picsart Drive by default on a best-effort basis; saving is not guaranteed. Requires a signed-in Picsart account.
picsart_view_image
ChatGPTFetches Picsart-hosted images and returns inline image content for visual inspection. Supports reviewing uploaded references, generated images, and moodboard images. Pass url for one image or urls for up to 6 images in one call. Accepts Picsart-hosted image URLs from generations, uploads, and Drive; images over 3MB are rejected with guidance. Video URLs are not supported. Read-only; spends no credits and works without authentication.
picsart_workspace_open
ChatGPTOpens Picsart: a page of ideas to start from -- a short film, motion design, a cartoon, creating and editing a video or an image, bold captions, a voiceover or dub, a reel from footage, and reframing a video for every size. Choosing one sends its request to this conversation, where it is carried out. Takes no input. Returns { settings }: the display settings (driveLayout, autoplayVideo), null when they could not be read.
import-claude-motion-from-url
Claude
