add_video_subtitles
ChatGPTWHAT — Transcribes the speech in a video and burns styled captions (subtitles) into the picture. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user asks to add captions or subtitles to a video, for example for Reels, TikTok or Shorts. NEXT — Video jobs take a while: follow a timed_out result with wait_for_run. PITFALLS — The video needs audible speech. Captions are burned in, not a separate subtitle file. config.styleId picks the look; language 'auto' detects it. Media inputs take { "kind": "video", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
cancel_run
ChatGPTWHAT — Cancels a run that is queued, running, or paused. Idempotent — cancelling an already-terminal run is a no-op. WHEN — Use when the user explicitly asks to stop a run, or when you detect a run will fail/produce wrong output and want to spare the credits. NEXT — No follow-up needed; the run's status moves to 'cancelled'. If you want to verify, call get_run({ run_id }). PITFALLS — Cancelling does NOT refund credits already consumed by completed nodes. There is no 'pause and resume' shape — cancel is terminal.
change_aspect_ratio
ChatGPTWHAT — Reframes an image to another aspect ratio and fills the new area with matching scenery (outpainting), so nothing is stretched. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Turning one image into other formats: a square post into a 9:16 story, a 16:9 banner or a 4:5 feed image. NEXT — Show the reframed image; call again per format. PITFALLS — config.model and config.targetAspectRatio are both required, and the ratio values depend on the model (ideogram-v3-reframe uses names such as landscape_16_9). Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
change_voice
ChatGPTWHAT — Re-speaks a voice recording in another voice while keeping the words, timing and emotion (voice changer). Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user wants their own recording in a different voice, or one consistent narrator across clips. NEXT — Use the audio as is, or bind it into generate_lipsync. PITFALLS — config.voice is required (a voice id from the list in the schema). Takes audio, not video. Media inputs take { "kind": "audio", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
delete_asset
ChatGPTWHAT — Moves an asset to trash (soft delete). It stops appearing in search, list_assets and previews immediately; a background job purges trashed assets after 30 days. WHEN — Use when the user asks to remove a specific image or file from their library. NEXT — The asset can be recovered from the Orisu app's trash until the 30-day purge; nothing in this connection restores it. PITFALLS — Requires the assets:write scope. Deleting an already-trashed or unknown id returns ASSET_NOT_FOUND.
edit_image
ChatGPTWHAT — Changes an existing image the way the instructions say: swap the background, change colors, add or remove an object, restyle it, fix details. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user has a photo or a generated image and asks to change something in it. NEXT — Show the edited image; run edit_image again on the result for further changes. PITFALLS — Needs inputs.input_image and either config.prompt or inputs.input_instructions. Output options (aspect ratio, resolution, quality, background) depend on the model. To only cut out the subject use remove_background. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
generate_image
ChatGPTWHAT — Generates one to four images from a text prompt, optionally guided by reference images (a product photo, a style or a logo). Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Product photos, packshots, lifestyle shots, ad creatives, social posts, illustrations. NEXT — Show the result. To change an existing image use edit_image; to animate it use generate_video. PITFALLS — Needs config.prompt or inputs.input_text_prompt. Aspect ratio and resolution options depend on the model. Reference images are { kind: 'image', assetId } references. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
generate_lipsync
ChatGPTWHAT — Makes the face in a photo or a video speak a given audio track: a talking-head clip from a portrait, or a video re-synced to a new voiceover. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Talking avatars, spokesperson clips, or matching a video to a dubbed or generated voiceover. NEXT — Create the voice track with generate_speech first if the user has none. Follow a timed_out result with wait_for_run. PITFALLS — inputs.input_audio is required, plus exactly one of input_image or input_video; each model accepts only some of these (listed in the config schema). Media inputs take { "kind": "image" | "video" | "audio", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
generate_music
ChatGPTWHAT — Composes an original music track from a description of genre, mood and instruments, with or without vocals. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Background music, jingles, intros, soundtrack for a product video. NEXT — Use the audio as is. PITFALLS — Needs config.prompt or inputs.input_description. Duration limits and lyrics support depend on the model; set force_instrumental for no vocals. The same config works for this operation inside run_typed_graph.
generate_sound_effects
ChatGPTWHAT — Generates a sound effect from a short description, such as a door creak, rain on a window or a whoosh transition. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — SFX for videos, UI sounds, ambience loops. NEXT — Use the audio as is. PITFALLS — Needs config.prompt or inputs.input_text. duration_seconds 0 lets the model choose (max 30). The same config works for this operation inside run_typed_graph.
generate_speech
ChatGPTWHAT — Turns text into natural speech in one of the listed voices and returns an audio file. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Voiceovers, narration, product video VO, reading a script aloud. NEXT — Use the audio as is, or bind it into generate_lipsync (talking avatar) with run_typed_graph. PITFALLS — Needs config.prompt or inputs.input_text. config.voice takes a voice id from the list in the schema; without one a British male narrator (George) is used. The same config works for this operation inside run_typed_graph.
generate_text
ChatGPTWHAT — Runs a language model once on a text prompt, optionally with images to look at, and returns the text. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Product descriptions, ad headlines, captions, image prompts or other short copy; describing what is in an image. NEXT — Use the text directly, or chain it into an image, video or voiceover step with run_typed_graph. PITFALLS — inputs.input_text_prompt is required. Pass images as { kind: 'image', assetId } references, not URLs. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
generate_video
ChatGPTWHAT — Generates a short video clip from a text prompt, optionally animating a start image (a product photo or a generated image). Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Product videos, social clips, b-roll, animating a still image. NEXT — Clips take a while: if the result says timed_out, follow it with wait_for_run. Add captions with add_video_subtitles. PITFALLS — Needs config.prompt or inputs.input_text_prompt. Some models need a start image and some refuse one (listed in the config schema). Duration, aspect ratio and audio options depend on the model. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
get_app
ChatGPTWHAT — Returns one published app: name, agent_id, version_id (the pinned version trigger_app runs), visibility, inputs (the input fields with their node ids) and outputs. WHEN — When you hold an app_id and need its input fields or the workflow it runs, before calling trigger_app. NEXT — Call trigger_app({ app_id, inputs }) with values keyed by input node id, then wait_for_run. get_run_inputs_schema({ app_id }) gives the exact value shape of each input. PITFALLS — An app id is not a workflow (agent) id; trigger_run wants this result's agent_id. The app runs its pinned version_id, not the workflow's latest version; publish_app again after a change.
get_brand_context
ChatGPTWHAT — Returns the workspace's brand knowledge as one block: the typed profile (name, palette, fonts, voice, market, guidelines) plus the facts the team has taught and confirmed. WHEN — Use BEFORE writing anything in the user's brand voice — copy, campaigns, product descriptions, social posts — instead of asking them to describe their brand again. Also use when they say 'our brand', 'our tone', 'how we usually say this'. NEXT — Write in the voice it describes and respect its rules. For something the block does not cover, call query_brain rather than guessing. PITFALLS — This is one brand per workspace, not a list. The block is capped, so it holds the top knowledge rather than everything — query_brain reaches the rest. Facts marked unconfirmed are the extractor's guesses awaiting human review; prefer confirmed ones when they conflict.
get_run
ChatGPTWHAT — Returns a run's current status and detail without waiting: status, top-level error / error_code / failed_node_id on failure, outputs (each node's merged result, asset URLs resolved), step_counts, and steps (failed first). WHEN — Use to inspect a run by id right now, for example to see why a past run failed or to check one from list_runs. Right after starting a run, prefer wait_for_run (same JSON, waits until the run ends). NEXT — On 'failed': read error + failed_node_id, change that step's config or inputs and run it again with the typed operation tools or run_typed_graph. On 'queued'/'running': call wait_for_run. On 'completed': take results from outputs. Hosts that support MCP Apps also show the outputs to the person in an inline media viewer. PITFALLS — Non-blocking: a running run returns its in-flight state, so use wait_for_run rather than polling this. trigger_run reuses the workflow's run in place, so read a failure here before re-running it. outputs.<node>.<port> is the full result; steps[].output is one iteration row.
get_run_inputs_schema
ChatGPTWHAT — Returns the input nodes of a saved workflow (agent_id, its latest version) or of a published app (app_id, its pinned version): node_id, node_type, label, required, value_type and an example value, plus agent_id and version_id. WHEN — Before trigger_run or trigger_app for a workflow or app whose inputs you have not seen yet, so the inputs map uses the right node ids and value shapes. NEXT — Build inputs as { [node_id]: value }: a string for a text input, an array of { kind, assetId } references (from upload_asset or list_assets) for an image, video or audio input. Then call trigger_run or trigger_app. PITFALLS — An app may be pinned to an older version than the workflow's latest, so pass app_id for apps. An app id passed as agent_id is resolved to the app. Media inputs take only asset references, not URLs.
list_assets
ChatGPTWHAT — Paginated, filterable listing of the org's asset library with full metadata + provenance (run/agent/node) and permanent URLs. Optionally returns inline thumbnails so you can see the page. WHEN — Use to BROWSE or enumerate assets — 'everything the Mon Cheri agent made last week', 'all videos', paging through a large library. For a name lookup use search({ kind: 'asset' }); to render specific ids at higher fidelity use preview_asset. NEXT — Page with cursor→next_cursor until next_cursor is null. Filter by media_kind / created_after / agent_id. Set include_thumbnails to view the page inline yourself; the person already sees the page's images, videos and audio in the inline media viewer on hosts that support MCP Apps. Reuse an asset via { kind, assetId } on an upload_* node input. PITFALLS — limit caps at 100; keep paging via next_cursor for more. include_thumbnails adds base64 — leave it off for bulk enumeration, on when the user is actually looking. Thumbnails only exist once the background pipeline has produced them (audio/document rows never have one).
list_runs
ChatGPTWHAT — Lists recent runs in the current org, newest first, with optional status / agent filters. WHEN — Use whenever the user references a run without giving an id ('show me the last failed run', 'what's still running'). Cheaper than calling get_run on ids blindly. NEXT — Failed runs already carry error_summary + failed_node_id here — often enough to act without another call. For per-step outputs and asset URLs, call get_run({ run_id }) (or wait_for_run to block until it finishes — same JSON). PITFALLS — Returns at most 50 rows per call (default 20) — there is no cursor pagination here; filter narrower by agent_id / status. error_summary and failed_node_id are null unless the run failed or was cancelled with a recorded reason. started_at is the run's creation time.
preview_asset
ChatGPTWHAT — Renders assets inline: returns image/audio bytes as viewable/playable media content blocks, plus each asset's metadata and a permanent URL. This is HOW you show an asset to the user in the chat. WHEN — Use whenever the user wants to SEE or hear an asset — 'show me that image', 'preview the last render', 'play the audio'. Prefer this over telling the user to open a URL, and over the orisu://assets/{id} resource (many hosts, e.g. ChatGPT, can't read resource URIs from a tool flow — they answer 'Unknown resource'). NEXT — Video (no inline block exists) and oversized media return url-only for you; on hosts that support MCP Apps (claude.ai, ChatGPT) the person sees and plays every image, video and audio asset in the inline media viewer, so you only need to surface the url elsewhere. To reuse an asset in a workflow, pass { kind, assetId } to an upload_* node input. PITFALLS — Max 8 ids per call; images/audio over ~5MB come back url-only (too big to inline). Ids from another org, or unknown ids, are reported in the text summary and skipped — never fatal.
query_brain
ChatGPTWHAT — Searches the workspace's brand knowledge in one call: the typed brand profile (voice, tone, guidelines, market, audiences, tagline, palette, fonts, word rules, channel tone) returned as profile_fields with source 'profile', plus semantic search over the brand facts the team has taught Orisu, returned as facts with source 'fact'. The query text is sent to a third-party embeddings model for that search; nothing is saved. WHEN — Use for a targeted question: 'what tone do we use in ads?', 'what are our brand colours?', 'how do they talk about pricing?', 'who is the audience for the refill line?'. Voice / tone / audience / colour / font questions are answered from profile_fields. NEXT — Use what comes back verbatim where it states a rule — profile_fields first (they are the brand's own settings), then facts. If both are empty, say so rather than inventing brand facts. PITFALLS — Returns nothing when the Brain holds no related knowledge — that is an answer, not a failure, and inventing a plausible-sounding brand rule is worse than admitting the gap. Confidence below 1 means a human has not confirmed it yet.
relight
ChatGPTWHAT — Changes the lighting of an image to match a short description, such as golden hour, soft studio light or neon from the left. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user wants different light or mood on an existing photo, or to match lighting across shots. NEXT — Show the relit image. PITFALLS — inputs.input_instructions (the lighting description) is required. config.initialLatent only hints at the light direction. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
remove_background
ChatGPTWHAT — Cuts the main subject out of an image and returns it on a transparent background. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Product cutouts, transparent PNGs, or preparing a subject to place on another background. NEXT — Show the cutout, or bind it into edit_image or generate_image in run_typed_graph. PITFALLS — One image per call. For a video use remove_video_background. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
remove_video_background
ChatGPTWHAT — Removes the background behind the person or product in a video and returns the subject on a transparent background. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user wants a green-screen-style cutout of a person or product in a clip, to place it over other footage. NEXT — Video jobs take a while: follow a timed_out result with wait_for_run. PITFALLS — outputCodec 'vp9' (default, WebM) keeps transparency; 'h264' does not. Set subjectIsPerson to false for products or objects. Media inputs take { "kind": "video", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
save_brand_fact
ChatGPTWHAT — Saves one durable fact about the brand to the workspace's shared Brain, where the whole team and every Orisu agent will see it. If it refines or contradicts a fact already saved, the older fact is replaced (kept only in history); the result lists the superseded fact ids. WHEN — Use when the user states something durable about their BRAND — identity, products, audience, voice, style rules, things they never do. 'Our audience is DTC skincare founders'. 'We never use exclamation marks'. NEXT — Nothing — it lands in the workspace's review queue for a human to confirm. Tell the user you saved it so they know where it went. PITFALLS — Durable brand truth ONLY. Not a scratchpad, not this conversation's preferences, not the user's personal habits, and never a one-off instruction like 'make this one bigger'. Write it atomic and self-contained — 'the primary colour is coral' beats 'it changed'. Saved facts enter a HUMAN REVIEW queue and are marked unconfirmed until someone on the team approves them.
search
ChatGPTWHAT — Searches the workspace's saved workflows (agents), published apps, runs or assets by free text and returns matching items with their ids. Read-only. WHEN — When the user refers to an earlier workflow, app, run or image by name or description. NEXT — Agent ids go to trigger_run or publish_app, app ids to trigger_app (app results also list agent_id, version_id and the input fields), run ids to get_run / wait_for_run, asset ids to the image inputs of the typed operations. PITFALLS — One kind per call. Matching is substring-based, not semantic. An empty query returns everything up to limit. An app id is different from its agent id.
transcribe_audio
ChatGPTWHAT — Transcribes the speech in an audio file into text, optionally labelling speakers. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Transcripts of interviews, voice notes or podcasts; getting a script to rewrite or translate. NEXT — Use the text directly, or bind it into generate_text or generate_speech with run_typed_graph. PITFALLS — Takes audio, not video (to caption a video use add_video_subtitles). language 'auto' detects it. Media inputs take { "kind": "audio", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
trigger_app
ChatGPTWHAT — Starts a new run of a published app with the given input values and returns the run_id. The app runs its published version, calls third-party AI model providers and spends workspace credits. Only apps whose published workflow is made entirely of the typed operations can run on this connection; anything else is refused before anything is queued or spent. WHEN — When the user asks to run a published app (from publish_app or search({ kind: 'app' })) with specific inputs. NEXT — The run continues in the background; read its status and outputs with wait_for_run. PITFALLS — Input values are keyed by input-node id (get_run_inputs_schema({ app_id }) lists them): a string for a text input, an array of { kind, assetId } references for an image, video or audio input. Each call is a new run and is billed. Edits made to the workflow after publishing are not included until the app is published again. Without max_credits, spend is limited only by the workspace's credit balance.
trigger_run
ChatGPTWHAT — Starts a run of an existing saved workflow and returns its run_id. Only workflows made entirely of the typed operations (text, image, video and audio inputs and the typed operation tools' steps) with settings those operations accept can run on this connection; anything else is refused before anything is queued or spent. The run calls third-party AI model providers and spends workspace credits. WHEN — When the user asks to run a workflow they saved earlier, found with search({ kind: 'agent' }) or created through run_typed_graph. NEXT — The run continues in the background; read its status and outputs with wait_for_run. PITFALLS — Each workflow has one working run: the call returns the same run_id and overwrites that run's previous outputs. Every step runs and is billed again. Without max_credits, spend is limited only by the credit balance. A retry without idempotency_key can bill a second run.
upload_asset
ChatGPTWHAT — Uploads a file (via URL or data URL) into Orisu's storage and creates an asset in the workspace library. WHEN — Use when the user provides an image, video or audio file the typed operations should work on, for example a photo for edit_image, a clip for add_video_subtitles or a recording for transcribe_audio. NEXT — Pass the result to a media input as { "kind": "image" | "video" | "audio", "assetId": <asset_id> } (kind = the asset's type): the inputs of the typed operation tools, an image_input / video_input / audio_input node in run_typed_graph, or a media input of trigger_run or trigger_app. PITFALLS — Provide either url or data_url, not both. data_url suits files under about 5MB, so pass a url for video. Media inputs take only the { kind, assetId } reference, not a bare asset_id.
upscale_image
ChatGPTWHAT — Enlarges an image 2x or 4x and sharpens detail. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user asks to upscale, enhance, sharpen or increase the resolution of a photo, for print or a large banner. NEXT — Show the upscaled image. PITFALLS — The scale factors offered depend on the model (aura-sr is 4x only). Large outputs cost more. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
upscale_video
ChatGPTWHAT — Increases the resolution of a video clip (to 1K-3K, or 2x/4x depending on the model). Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — The user asks to upscale, enhance or sharpen a video, or to make a low-resolution clip HD. NEXT — Video jobs take a while: follow a timed_out result with wait_for_run. PITFALLS — target_resolution values depend on the model. Cost grows with clip length and output resolution. Media inputs take { "kind": "video", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
validate_typed_graph
ChatGPTValidates a workflow graph built only from these operations: text_input, image_input, video_input, audio_input, generate_text, generate_image, edit_image, remove_background, upscale_image, change_aspect_ratio, relight, vectorize_image, generate_video, upscale_video, remove_video_background, add_video_subtitles, generate_lipsync, generate_speech, generate_music, generate_sound_effects, change_voice, transcribe_audio, dub_media (each node's description in the schema says what it does). Every config field, model choice and binding is checked against the closed schema; nothing is saved, run or charged. Returns ok or a list of issues with node ids.
vectorize_image
ChatGPTWHAT — Traces a raster image (PNG or JPG) into a scalable SVG vector. Runs once as a saved one-step workflow: the cost is estimated first, then a third-party AI model provider is called and credits are spent. Returns the run status and outputs. WHEN — Logos, icons and flat illustrations that need to scale cleanly or be edited in a vector tool. NEXT — Show or download the SVG. PITFALLS — Works best on flat graphics; photos become many shapes. Media inputs take { "kind": "image", "assetId": "..." } references from upload_asset or list_assets, not URLs. The same config works for this operation inside run_typed_graph.
wait_for_run
ChatGPTWHAT — Waits for a run to finish and returns the run JSON (same shape as get_run) when its status becomes completed, failed or cancelled, or when timeout_ms elapses. WHEN — Use after starting a run (trigger_run, or a typed operation call that came back with timed_out) instead of calling get_run in a loop. NEXT — If 'completed': the result embeds thumbnails of the image outputs plus outputs and steps with asset URLs. If 'failed': error, error_code and failed_node_id are top-level; fix that step and run again. If timed_out: true: call wait_for_run again. Hosts that support MCP Apps also show the outputs in an inline media viewer. PITFALLS — timeout_ms is capped at 110000 (about 110s); long runs may need a few calls. outputs.<node>.<port> is the full result while steps[].output is one iteration row. Embedded thumbnails are capped at 12 and appear once the background pipeline has produced them.
who_am_i
ChatGPTWHAT — Returns the connection's identity: org id, user id (if any), client id, auth source, granted scopes, and the org's workspaces (with the default one flagged). WHEN — Call once at the start to confirm the connection works and to see which organization and workspaces you are working in. NEXT — Check the scopes before running anything: generating media needs 'runs:execute'. Most orgs have one workspace. When there are several and the user wants a specific one, pass its id as workspace_id to the typed operation tools or search; otherwise the default is used. PITFALLS — userId is null on API-key connections. Don't pass workspace_id unless the user actually manages several workspaces.
