Studio tools Beta

The Studio tools let an MCP client (e.g. Claude or ChatGPT) read and edit a heycreo design: its elements, text, images, layout, timeline, controls and formats. Unlike the data tools, they understand the full design document model.

How targeting works

You point a Studio tool at a document, not at a browser session. Every document-level tool takes one of:

templateId: a reusable template (from get-templates), or
designId: a free-canvas design (post).

Provide exactly one of the two. The tool then operates on the server-authoritative document:

No editor tab is required. Edits are applied and persisted server-side; nobody needs to have the design open in Studio.
It's collaborative when someone is watching. Each change is broadcast live, so any human who has the design open sees it update in real time (the connected assistant, e.g. Claude or ChatGPT, even appears as a participant in the editor while it works). If no one is watching, the changes are simply saved.
Reads are always current. A read reflects the latest saved state, including the assistant's own edits, so you can call studio_get_document again after a write to confirm the result.

The document must belong to the same organization as the API key. A few tools are org-level and take no target at all: studio_get_capabilities, studio_get_fonts and studio_list_formats.

Recommended first call

Call studio_get_capabilities once at the start of a session. It returns the full Studio design manual (coordinate system, units, shape anatomy, z-order, animation and camera semantics, controls) plus a machine-readable catalog of every operation you can run through studio_call. Then call studio_get_document to learn the element IDs and active page before editing.

Typical workflow

studio_get_capabilities                      → learn the model + tool catalog (once)
studio_get_document({ templateId })          → read element IDs, active page, coordinate space
studio_call({ templateId, tool, args })      → make an edit (e.g. studio_create_text)
studio_get_screenshot({ templateId })        → visually verify the result

To start from scratch, studio_create_template returns a new templateId you then edit with the same tools.

studio_get_document

Read the live, authoritative state of a design. Returns a rich snapshot: canvas size + coordinate system, default element sizes, duration, the multi-page list, timeline tracks/clips, camera, template controls, and the full element list in stacking order (z-index, id, type, name, position, size, style summary, content, animations, control bindings). This is the same document view the in-app agent uses; call it before editing.

Parameter	Type	Required	Description
`templateId`	`string`	Conditional	Id of the template to read (from `get-templates`). Provide this or `designId`.
`designId`	`string`	Conditional	Id of the free-design post to read. Provide this or `templateId`.

Returns the snapshot as formatted text. Errors (document not found, wrong org, no access) are returned as an error string.

studio_get_capabilities

Return the complete Studio design manual plus the catalog of every high-level tool callable via studio_call (each with name, description and parameter list), the available shape kinds, position anchors, and raw editor command ids. Org-level: takes no arguments.

studio_get_fonts

List every font available to the organization (Google Fonts the org added + custom uploads) with the concrete weights each family supports. Org-level: no target needed. Call this before setting a font: use the returned name verbatim as style.fontFamily and one of the listed weights as style.fontWeight. Never invent a font name.

Returns { count, fonts: [{ name, type, category, weights }], usage }.

studio_list_formats

List every format/size that may be added to a design for this organization: standard presets (social, web, print) plus the org's own custom formats. Each entry has an id, name and width×height. Pass one of these ids as formatId to studio_add_size (via studio_call) or to studio_create_template. The server only accepts known formats; invented sizes are rejected. Org-level: no target needed.

Returns { count, formats: [{ id, name, width, height, supportsPdf }], usage }.

studio_create_template

Create a new, empty template and return its templateId. Use this when the user wants a brand-new design. After creation, edit it with studio_call using the returned id.

Parameter	Type	Required	Description
`name`	`string`	Yes	Descriptive template name, e.g. `"Webinar Announcement"`
`formatId`	`string`	Yes	Starting canvas size id (from `studio_list_formats`). Invented sizes are rejected
`type`	`string`	No	`image` (static, default) or `video` (motion/timeline)

Returns { ok: true, templateId, name, type, sizeId, note }. The template stays a draft until you publish it.

studio_get_screenshot

Render a PNG of how a design currently looks, using the same server-side renderer as exports. Use it to visually verify an edit or understand a layout you can't infer from the text snapshot. Returns an image of the document's authoritative state (your most recent edits included).

Parameter	Type	Required	Description
`templateId`	`string`	Conditional	Id of the template to render. Provide this or `designId`.
`designId`	`string`	Conditional	Id of the free-design post to render. Provide this or `templateId`.
`sizeId`	`string`	No	Render a specific format/size. Defaults to the first size.
`pageId`	`string`	No	For multi-page/carousel sizes: render a specific page. Defaults to the first page.

studio_call

The primary way to edit a design. Runs ONE high-level Studio tool against the target document. The tool encapsulates all editor conventions (tracks, z-order, units, bounding boxes). Write tools are applied and persisted server-side (and pushed live to anyone viewing the document); read tools just return their data.

Parameter	Type	Required	Description
`templateId`	`string`	Conditional	Id of the template to edit. Provide this or `designId` (not inside `args`).
`designId`	`string`	Conditional	Id of the free-design post to edit. Provide this or `templateId`.
`tool`	`string`	Yes	Name of the Studio tool to run, e.g. `studio_create_text`
`args`	`object`	No	The target tool's argument object (without `templateId` / `designId`)

A successful write returns { ok: true, tool, applied: <n>, ... }. An unknown tool returns an error plus the list of availableTools. Call studio_get_capabilities for each tool's exact parameters.

Sub-tool catalog

studio_call dispatches to ~50 high-level Studio tools. The list below is grouped for orientation; studio_get_capabilities returns the authoritative, machine-readable catalog with full parameters.

Group	Tools
Create elements	`studio_create_scene`, `studio_create_text`, `studio_create_shape`, `studio_create_image`
Edit elements	`studio_update_content`, `studio_update_style`, `studio_set_color`, `studio_move_element`, `studio_set_position`, `studio_position_element`, `studio_rotate_element`, `studio_resize_element`, `studio_set_text_size`, `studio_delete_elements`, `studio_duplicate_elements`
Pages (slides within one size)	`studio_add_page`, `studio_delete_page`, `studio_duplicate_page`, `studio_reorder_pages`
Formats / sizes	`studio_add_size`, `studio_remove_size`
Layer / z-order	`studio_bring_to_front`, `studio_send_to_back`, `studio_move_layer`
Animation	`studio_animate_path`, `studio_animate_property`, `studio_remove_animation`
Timeline / tracks	`studio_set_clip_timing`, `studio_trim_element`, `studio_move_element_to_track`, `studio_create_track`, `studio_update_track`, `studio_create_track_group`, `studio_update_track_group`, `studio_delete_track_group`, `studio_reorder_track_groups`, `studio_assign_track_to_group`
Camera	`studio_set_camera`, `studio_animate_camera`
Document / page settings	`studio_set_duration`, `studio_set_page_duration`
Controls (template form fields)	`studio_list_controls`, `studio_create_control`, `studio_update_control`, `studio_link_control`, `studio_delete_control`
Read helpers	`studio_get_document_summary`, `studio_list_elements`, `studio_get_element`, `studio_find_elements`, `studio_get_timeline`, `studio_get_camera`, `studio_measure_layout`

Example

{
  "tool": "studio_call",
  "arguments": {
    "templateId": "<template id>",
    "tool": "studio_create_text",
    "args": {
      "content": "Summer Sale",
      "anchor": "top-center",
      "style": { "fontFamily": "Inter", "fontWeight": "700", "color": "token:primary" }
    }
  }
}

Color tokens & fonts

Use studio_get_fonts for valid font names/weights and get-color-palettes for palette roles. A color value of token:primary (or token:accent, token:background, …) links the element to a palette role, so swapping the palette re-skins the design. Use a raw hex for one-off colors.

studio_apply_commands

Last-resort tool for applying low-level editor commands directly. Prefer studio_call with a high-level tool whenever one fits. Call studio_get_document first to learn element IDs and the active page id. All commands in one call are applied together and persisted server-side.

Parameter	Type	Required	Description
`templateId`	`string`	Conditional	Id of the template to edit. Provide this or `designId`.
`designId`	`string`	Conditional	Id of the free-design post to edit. Provide this or `templateId`.
`commands`	`array`	Yes	Ordered list of `{ id, payload }` commands

Common command ids: element.add ({ pageId, element }), element.move ({ ids, dx, dy }), element.updateContent ({ id, content }), element.updateStyle ({ id, patch }), element.delete ({ ids }). An unknown id returns an error with the full validCommandIds list.

See also: Brand Kit tools for inserting and saving reusable design snippets on a design.

How targeting works​

Typical workflow​

studio_get_document​

studio_get_capabilities​

studio_get_fonts​

studio_list_formats​

studio_create_template​

studio_get_screenshot​

studio_call​

Sub-tool catalog​

Example​

studio_apply_commands​