Orisu

WHAT — 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.

generate_video

WHAT — 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_speech

WHAT — 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_image

WHAT — 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_music

WHAT — 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_text

WHAT — 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.

who_am_i

WHAT — 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.

get_run_inputs_schema

WHAT — 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_lipsync

WHAT — 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.

list_runs

WHAT — 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.

delete_asset

WHAT — 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.

preview_asset

WHAT — 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_app

WHAT — 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

WHAT — 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.

relight

WHAT — 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.

remove_video_background

WHAT — 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_background

WHAT — 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_app

WHAT — 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.

trigger_run

WHAT — 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.

query_brain

WHAT — 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.

search

WHAT — 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.

save_brand_fact

WHAT — 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.

transcribe_audio

WHAT — 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.

upload_asset

WHAT — 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.

upscale_video

WHAT — 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_image

WHAT — 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_brand_context