add_document_context
ChatGPTPrepares an article, blog post or document as the source to create content from. Requires account_id and brand_id from list_brands, and either url (a public link the user shared) or media_asset_id (a document they uploaded, once get_media_asset says READY). Munch extracts the text now, which can take up to a minute. When ingest_status is READY, pass media_asset_id as document_id to create_project; FAILED means the text could not be used (ingest_error says why). Adding the same source again returns its current state.
attach_media
ChatGPTAdds a file the user attached in this conversation (an image, a video, or a PDF, Word or text document) to the brand's Munch media. Use it when the client hands you the attachment as a file object with a download_url (ChatGPT does); otherwise use create_media_upload. Requires account_id and brand_id from list_brands. Returns media_asset_id with status PENDING while Munch downloads the file: call get_media_asset until it is READY before using it.
cancel_scheduled_export
ChatGPTCancels a scheduled post that hasn't gone out, as deleting it from Munch's planner does; it can't be undone (schedule the item again instead). Requires account_id and brand_id from list_brands and export_id from get_exports or schedule_post. Confirm with the user first. Cancelling a cancelled post changes nothing.
choose_subtitle_template
ChatGPTShows the user the subtitle templates for a video project, with animated previews, so they can pick the look of the captions; the brand's default is selected. Requires account_id and brand_id from list_brands, and type: AUTO_CLIP, AUTO_CROP or AUTO_CAPTIONS. The picked template goes to create_repurpose_project as subtitles_template_id.
create_media_upload
ChatGPTStarts uploading a file the user gave you (an image, a video, or a PDF, Word or text document) into the brand's Munch media. Files over 100 MB go through the brand's media library instead. Use it when you can send the file bytes yourself (for example from a code execution environment); if the file reached you as an attached-file object with a download_url, use attach_media instead. Requires account_id and brand_id from list_brands, and the file's name, MIME type and exact size. Returns media_asset_id and upload_url: send one HTTP PUT to upload_url with the raw file bytes as the body and exactly the upload_headers, before expires_at. Then call get_media_asset until its status is READY. If you can't upload files at all, call get_recent_uploads and ask the user to upload the file at media_library_url; when they say it's done, find it there.
create_project
ChatGPTCreates new carousel and poster content for the brand from its super brand (on-brand) templates; Munch picks the templates. Requires account_id and brand_id from list_brands, and exactly one source: idea_id (suggest_topics or validate_topic) or document_id (add_document_context, READY). Optionally the user's images in media_asset_ids, all READY in get_media_asset: never create while one is still uploading. Settings left out use the brand defaults from get_creation_options. Before calling it, restate the source and the settings it will use in one short message, and call it only after the user's explicit yes. Generation runs in the background and takes a few minutes: poll get_project with project_id about every 30 seconds. Each call creates a new project, so call it once per request.
create_repurpose_project
ChatGPTCreates a repurpose project from one video. Requires account_id and brand_id from list_brands, type, name, and source: a video url, or the media_asset_id of a video that get_media_asset reports READY (from create_media_upload, or get_recent_uploads when the user uploaded it in Munch). Use only values from get_repurpose_options for this type; settings left out use the brand's defaults. Before calling it, restate the type, source, aspect ratio and platforms, captions and template, clip length and language, and that it uses video minutes (minutes left from get_repurpose_options). Call it only after the user's explicit yes. Each call creates a new project and uses minutes, so call it once per request. The project takes up to about 45 minutes: tell the user, and that they can ask about it later in this chat.
create_voiceover_project
ChatGPTCreates a Generated Video project (a voiceover video). Requires account_id and brand_id from list_brands, and idea_id (suggest_topics or validate_topic). Before calling it, set up the settings with the user, offering only values from get_voiceover_options: template, voice, length, platform, tone, goal and narrator perspective, plus their own images or videos (media_asset_ids, READY in get_media_asset). Settings the user doesn't choose use the brand's defaults there. Then restate them all and that it uses one of the account's monthly Generated Videos, and call it only after the user's explicit yes. Each call creates a new video, so call it once per request. The video takes a while: tell the user, and that they can ask about it later in this chat.
download_item
ChatGPTPrepares one item's file for download, as Download in Munch Studio does: the video of a clip or voiceover video, the image of a poster, or a ZIP of the slides of a carousel. Requires account_id and brand_id from list_brands, and item_id from get_project, get_repurpose_project, get_voiceover_project or get_exports. Returns export_id, and download_url when the file is already available. Then follow next_step.
edit_brand_book
ChatGPTChanges fields of the brand's brand book, the profile Munch writes on-brand content from (see get_brand's brand_book). Only the given fields change; null clears a text field. A list field replaces the current list, as the app saves it: to add or remove one item, send the whole new list. Requires account_id and brand_id from list_brands, and at least one field. Before calling it, confirm the exact change with the user: each field and its new value. Returns the brand book after the change and changed_fields. The brand kit (colors and fonts) can't be changed with it. Needs permission to edit the brand.
edit_item
ChatGPTRedraws one of the brand's on-brand posters or carousels from a written instruction. This is a visual editor: it changes what's in the slide/s images (their text, layout, colors and elements, or adding a logo or photo). It doesn't change the post's caption. The caption can be changed when publishing, with post_now, schedule_post or edit_scheduled_export. Your job is to understand the visual changes the user wants, and turn them into one clear instruction a generative image model can follow to redraw the item. Before calling this tool, confirm the changes with the user in plain, everyday words: what will look different, on which slide/s. Never show the instruction itself; it's written for the image model, not for the user. To see the item, look at its images from get_item: slide n is images[n - 1]. When the user wants their logo or themselves in the content, get_brand returns the brand's saved logos and owner photos to suggest. A new image can be added with create_media_upload or attach_media, and saved for next time with set_brand_asset. Pass the images the edit uses as attachments, each with its role. The result is new item(s) in the same project; the original isn't changed. Follow next_step. Requires account_id and brand_id from list_brands, and item_id from get_project.
edit_scheduled_export
ChatGPTChanges a scheduled post that hasn't gone out: its time, its account, or its caption, title or first comment. Only the given fields change. Requires account_id and brand_id from list_brands and export_id from get_exports or schedule_post; scheduled_to needs the user's timezone. A post can't be changed within 30 minutes of its time, and a new time must be at least 30 minutes ahead. Confirm the change with the user first.
get_brand
ChatGPTGets one brand's profile: name, website, business identity (description, industry, tone, goals, keywords, content language, contact details) and its content strategy (target audience, active platforms). Requires account_id and brand_id from list_brands. Use it to write or judge on-brand content. identity or strategy is null while the brand has none yet. brand_book is the full brand book: identity and contact, audience and positioning, voice, content guidance, and the brand kit (colors and fonts, read-only); an unset field is null or empty. edit_brand_book changes it. logos and owner_photos are the images the brand keeps for edits: its logos and photos of the business owner (empty when none are saved; see set_brand_asset).
get_creation_options
ChatGPTGets what new content can be created with for the brand, before create_project. Requires account_id and brand_id from list_brands. has_on_brand_templates false means Munch cannot create content for this brand yet: stop and ask the user to set up their super brand content in Munch Studio first. defaults are the settings used when create_project leaves them out (platforms, tones, goal, language, image_freedom, fill_gaps_sources); options lists the valid values. Briefly tell the user the current settings and that they can change them, without encouraging changes; skip this when they already said what they want.
get_exports
ChatGPTLists the brand's published and scheduled posts in a time window, oldest first, as Munch's planner shows them: platform, account, state, time, caption and title, and why a post failed. Requires account_id and brand_id from list_brands, and from / to with the user's UTC offset (at most 62 days apart). Show the times in the user's timezone, and link planner_url. Posts WAITING_FOR_ACCOUNT need an account connected at integrations_url.
get_item
ChatGPTGets one generated content item in full: every slide image in order and its caption. Requires account_id and brand_id from list_brands, and item_id from get_project. Before edit_item, look at its images to know the slides: slide n is images[n - 1]. To show one item to the user, use preview_item. When building a preview page from get_project's next_step, use the results only for the page; don't also show each item in chat.
get_media_asset
ChatGPTChecks whether a file added to the brand's media is ready to use. Requires account_id and brand_id from list_brands, and media_asset_id. status is PENDING while the file is still uploading or downloading (check again in a few seconds), READY when it can be used, and FAILED when it never arrived: tell the user and leave it out, add it again, or ask them to upload it in Munch's media library (get_recent_uploads gives the link). type is the file's kind: IMAGE, VIDEO or DOCUMENT. Never create a project while a file the user wants is PENDING.
get_next_slots
ChatGPTGets the brand's upcoming posting slots from its content strategy, per platform: the rest of this week and the next 7 days, each slot with its time, post type and content pillar, whether it is still free, and whether the platform is connected. Requires account_id and brand_id from list_brands, and the user's timezone: slot times are returned in it (no offset), and it decides which slots are already taken. Say the timezone when you present the times. If a platform is not connected but has taken slots, tell the user posts are scheduled there while the account is disconnected. Use it to suggest when to post.
get_project
ChatGPTGets the progress and results of a carousel and poster project: one created with create_project, or an earlier one found with list_projects. Requires account_id and brand_id from list_brands, and project_id. Lists the items of every run of the project, edits included, without the ones the user archived; status is the latest run's. While status is not COMPLETED or FAILED, generation is still running: wait about 30 seconds and call again. Items appear as they are generated; each has one thumbnail_url. When status is COMPLETED or FAILED, follow the next_step in the result. With run_id (following an edit), status and items are that run's only, and there's no next_step: follow edit_item's.
get_publish_accounts
ChatGPTLists the brand's social accounts per platform: each account's name, its state (CONNECTED or NEEDS_RECONNECT) and which one is the default. Requires account_id and brand_id from list_brands. Call it before publishing or scheduling, and confirm with the user which account to use on each platform: propose the default and name the others when there are several. A platform without accounts is not connected. To post now, every chosen account must be CONNECTED: otherwise send the user to integrations_url (or, when it's missing, the brand's Integrations page in Munch Studio) to connect or reconnect it.
get_publish_status
ChatGPTGets the state of published or scheduled posts by export_id: PUBLISHED, FAILED (with the reason), SCHEDULED, WAITING_FOR_ACCOUNT, CANCELLED, or still in progress. Requires account_id and brand_id from list_brands, and export_ids from post_now, schedule_post, get_exports or download_item. For a download, PUBLISHED means the file is ready and download_url is the link to give the user. Follow next_step when it is set.
get_recent_uploads
ChatGPTLists the brand's latest uploads in Munch, newest first: each file's name, type, size, upload time and status, and media_library_url, the page where the user uploads a file themselves. Use it to find a file the user added there, for example after you sent them to media_library_url because you couldn't upload it. Requires account_id and brand_id from list_brands; kind narrows the list to IMAGE, VIDEO or DOCUMENT. Before using a file, confirm its name with the user. While its status is PENDING, wait with get_media_asset until it is READY.
get_repurpose_options
ChatGPTGets what a repurpose project of one type can be created with, as Munch's project wizard offers it: aspect ratios, platforms (up to max_platforms), clip lengths, languages, subtitle templates, the source video limits, the account's video minutes and the brand's defaults. Requires account_id and brand_id from list_brands, and type: AUTO_CLIP (short clips from a long video), AUTO_CROP (resize a video) or AUTO_CAPTIONS (add captions to a video). Offer only these options; never invent others.
get_repurpose_project
ChatGPTGets the progress and clips of a repurpose project: one created with create_repurpose_project, or an earlier one found with list_projects. Requires account_id and brand_id from list_brands, and project_id. While status is PROCESSING, stage says where it is. When COMPLETED, clips lists the results in order, each with item_id, title, start and end, and thumbnail. When FAILED, error_reason says why. When next_step is set, follow it.
get_voiceover_options
ChatGPTGets what a Generated Video (Munch's name for a voiceover video) can be created with, as Munch's wizard offers it: video templates, narrator voices (each with its language and a sample), video lengths in seconds, platforms, tones, goals, narrator perspectives, how the user's own images and videos are used, the account's monthly Generated Videos and the brand's defaults. Requires account_id and brand_id from list_brands. When videos.can_create is false the account has no voiceover videos left and the lists are empty. Offer only these options; never invent others.
get_voiceover_project
ChatGPTGets the progress and videos of a voiceover project created with create_voiceover_project. Requires account_id and brand_id from list_brands, and project_id. status is PROCESSING while the video renders, then COMPLETED or FAILED. When COMPLETED, videos lists the videos, newest first, each with item_id, title, length, thumbnail and video_url. When FAILED, error_reason says why. When next_step is set, follow it.
list_brands
ChatGPTStart here: call before other Munch tools. Lists the brands in all the user's Munch accounts, plus this user's plan, role and available Munch tools in each account. Use the returned brand_id (with its account_id) with other tools. Also answers questions like "which brands do I have in Munch?".
list_projects
ChatGPTFinds the brand's projects, newest first: carousels and posters, video projects (clips, resize, captions) and Generated Videos (voiceover videos), ones created here or in Munch Studio. Requires account_id and brand_id from list_brands. When the user names a project, pass part of that name as query; omit it for the most recent ones. Pass kind when the user means one kind of project. Then read the one the user means, asking them to pick when several match: get_project when type is CAROUSEL_POSTER, get_repurpose_project for AUTO_CLIP, AUTO_CROP and AUTO_CAPTIONS, get_voiceover_project for VOICE_OVER.
post_now
ChatGPTPublishes one item now to one or more social platforms, through the account confirmed with the user on each (from get_publish_accounts). Requires account_id and brand_id from list_brands, item_id from get_project, and one target per platform. Every account must be CONNECTED, or nothing is posted. Optional caption, title and first_comment replace the item's own on every platform. Then follow next_step to track the posts with get_publish_status.
preview_item
ChatGPTShows one generated item to the user as an interactive preview: its slides, title and full caption, or a clip or voiceover video that plays, with a link to edit it in Munch. Use it when the user asks to see one item, and before publishing or scheduling one so they see exactly what will be posted. Requires account_id and brand_id from list_brands and item_id from get_project, get_repurpose_project, get_voiceover_project or get_exports; project_id adds a link to the project in Munch Studio.
preview_project
ChatGPTShows a finished project to the user as an interactive preview: every item with its slides, title and caption, every clip of a video project, or every video of a Generated Video project, with its thumbnail and title. Requires account_id and brand_id from list_brands, and the project_id of a project that get_project, get_repurpose_project or get_voiceover_project reports COMPLETED. Call it once, when the user asks to see the whole project or a status tool says to; to play one video, use preview_item.
schedule_post
ChatGPTSchedules one item to post at a future time on one or more social platforms, through the account confirmed with the user on each (from get_publish_accounts). Requires account_id and brand_id from list_brands, item_id from get_project, scheduled_to with the user's timezone, and one target per platform. On a platform with no account, schedule only when the user agrees, with allow_without_account: the post then waits for an account to be connected. Optional caption, title and first_comment replace the item's own on every platform. Then follow next_step.
set_brand_asset
ChatGPTSaves one of the brand's images as its logo or as a photo of the business owner, so later edits can use it. Use it only when the user says that's what the image is. A logo is added next to the existing ones and never replaces them. Requires account_id and brand_id from list_brands, and the media_asset_id of a READY image. Returns the brand's logos and owner photos after the change.
suggest_topics
ChatGPTSuggests topics for new content from the brand's own Munch topic ideas: each has an id, title, theme and description. Use it when the user wants content but has no topic of their own. Requires account_id and brand_id from list_brands. Show the topics as a numbered list and let the user pick one; its id is the idea_id for create_project. For more options, call again with the ids already shown in excluded_ids. An empty list means the brand has no topic ideas yet: offer to use their own topic (validate_topic) instead.
update_strategy_platforms
ChatGPTAdds and/or removes platforms in the brand's content strategy, which decides where Munch plans content. Requires account_id and brand_id from list_brands, and at least one platform in add or remove (never the same platform in both). Adding a platform already there, or removing one that is not, changes nothing. Returns the platforms after the change. Needs permission to edit the brand.
validate_topic
ChatGPTTurns the user's own topic into a Munch idea for the brand, after checking it fits. Use it when the user has their own topic, or one you developed together; pass what the content is about, not design or scheduling instructions. Requires account_id and brand_id from list_brands. When is_valid is true, use idea_id with create_project. When false, reasons explain why (codes: NON_ACTIONABLE_VISUAL_DIRECTION, NON_ACTIONABLE_SCHEDULING, PROMPT_INJECTION_ATTEMPT, TOO_SHORT_OR_VAGUE, OFF_TOPIC_FOR_BRAND, UNSAFE_CONTENT); explain them to the user and help them rephrase. Takes up to half a minute.