Skip to main content
Glama
Sign In

switch

by ai.switchapp
OverviewDiscussionsAdmin

Talking Avatar Video

talking_avatar_video

Turn a face photo into a lip-synced talking-head video that speaks your text (or your audio). Provide image_url (a clear face photo) and either script (text to speak, max 2500 characters) or audio_url. Optional voice_id / language / voice_settings. Renders in ~1-5 minutes (single call, returns the finished branded video) and is saved to your library. PRICE: Priced per second of the speech (your audio, or the script once spoken; a part second counts as a whole one), charged when the speech is ready and before the video is made, and returned if it fails. Pass seconds with quote_only for a total (suggest_speech_seconds tells you how long a script runs). Pass quote_only: true first to get the exact price; nothing is made and nothing is charged. To run it (not for a quote) send image_url.

Input Schema

NameRequiredDescriptionDefault
scriptNoText the avatar speaks. Max 2500 characters. Required unless audio_url is given.
secondsNoquote_only: how many seconds of speech, for a total price.
languageNoOptional language code (default en).
voice_idNoOptional voice id (from clone_voice / your library).
audio_urlNoPre-recorded audio to lip-sync instead of generating speech from script: an https link, a Switch audio take id (from generate_speech or generate_audio), or the asset_id of an audio upload.
image_urlNoA clear face photo: a picture id from list_my_assets (a made or uploaded picture) or an https link. Required.
quote_onlyNotrue answers the price only: nothing is made and nothing is charged.
voice_settingsNoOptional: { stability, similarityBoost, style, useSpeakerBoost } 0-1.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / image_url / description
      Previous value: -"A clear face photo (Switch/public URL). Required."New value: +"A clear face photo: a picture id from list_my_assets (a made or uploaded picture) or an https link. Required."
  2. Changed1 schema field changed
    • changedInput schema / properties / audio_url / description
      Previous value: -"Pre-recorded audio URL to lip-sync instead of generating speech from script."New value: +"Pre-recorded audio to lip-sync instead of generating speech from script: an https link, a Switch audio take id (from generate_speech or generate_audio), or the asset_id of an audio upload."
  3. Changed3 schema fields changed
    • addedInput schema / properties / quote_only
      Added value: +{
+  "description": "true answers the price only: nothing is made and nothing is charged.",
+  "type": "boolean"
+}
    • addedInput schema / properties / seconds
      Added value: +{
+  "description": "quote_only: how many seconds of speech, for a total price.",
+  "type": "number"
+}
    • removedInput schema / required
      Removed value: -[
-  "image_url"
-]
  4. First observed

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations by disclosing the cost model (per second of speech, part seconds rounded up), the charging timing (charged when speech is ready, before rendering, refunded on failure), the ~1-5 minute render with no polling since it returns the finished video, and that output lands in the library. For a paid, non-destructive mutation with openWorldHint, this is exactly the context an agent needs before spending money.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool makes and the required inputs, then moves to timing and pricing, then the quote-first workflow. The pricing/quote_only point is restated a few times but each restatement clarifies a different step (quoting vs. charging vs. rerunning), so it earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, nested-object, no-output-schema generation tool, the description covers inputs, cost, latency, refund behavior, and storage destination. Only minor gaps remain (output format/aspect ratio or how to find the saved video), which are not blocking for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds relational semantics the schema can't: image_url is the trigger to actually run, seconds is only meaningful paired with quote_only to produce a total, and script/audio_url are alternatives with a 2500-character cap. Slight redundancy with the schema keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb-and-resource statement: turns a face photo into a lip-synced talking-head video speaking text or supplied audio, and lists the required inputs. An agent understands exactly what it produces. It does not, however, distinguish itself from close siblings like lip_sync_video or sync3_lip_sync_video, so a caller can't rule those out from this text alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Strong sequencing guidance: 'Pass quote_only: true first to get the exact price' then 'To run it (not for a quote) send image_url', plus the pointer to suggest_speech_seconds for script duration and the script-xor-audio_url rule. The main gap is that no alternative sibling (lip_sync_video for an existing video) is named as a when-not condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All switch toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources