Skip to content
ShapelessAI← Back
The agent team

Cast actors and voices

The account's actors: the founder as themself, and any character the videos are narrated or fronted by.

View as Markdown

Read the roster with each voice and its locks, create or edit an actor, archive one, and give an actor a voice: designed from a description, or spoken on demand. Voice work spends credit and says so in the response. A job that names an actor uses that voice.

Ask in plain words

  • "design a calm British narrator voice"
  • "which actors do I have and what do they sound like"

From an agent host (MCP)

Server: https://shapelessai.com/mcp (add it to your host).

  • characters_list: The account's actors: who they are, what their voice is, and which parts are locked. voiceDescription is the casting direction a designed voice was written from - read it before designing another one, and reuse the actor that already fits. Needs the read scope.
  • characters_voice: SPENDS CREDIT: gives an actor a voice. description designs one from casting direction (kept on the character, so later runs can reuse the actor). Returns the voice id, a preview clip and what it cost. Needs the write scope.

From code (REST)

Bearer API key with the scope each call names (auth, OpenAPI).

  • GET /api/characters (read scope): The actor roster: identity, voice, locks.
  • POST /api/characters (write scope): Create an actor: {name, bio?, isUser?}.
  • GET /api/characters/{id} (read scope): One actor.
  • PATCH /api/characters/{id} (write scope): Edit an actor, including its locks: {name?, bio?, styleRules?, faceLocked?, voiceLocked?, styleLocked?, portraitMediaKey? (null clears it), faceRefKeys? (at most 12)}.
  • DELETE /api/characters/{id} (write scope): Archive an actor.
  • POST /api/characters/{id}/voice (write scope): Design or speak a voice: {action: design, voicePrompt} | {action: speak, text} (billed like POST /api/speech).

From a terminal (CLI)

  • shapeless characters list
  • shapeless characters voice

Example

curl -s https://shapelessai.com/api/characters/<id>/voice -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"action":"design","voicePrompt":"Calm, warm, British, unhurried."}'
// MCP tool call
{ "tool": "characters_voice", "arguments": { "character": "tal", "description": "Calm, warm, British, unhurried." } }
shapeless characters voice tal --describe "Calm, warm, British, unhurried."

Refusals

StatusMeaning
400Not JSON, no name, or a name over 80 characters.
404No such actor on this account.
400Not JSON, nothing to change, or a portrait or face reference that is not in this account's library.
400Not JSON, no such action, an empty voicePrompt, a speak text empty or over 2000 characters, speak before the actor has a voice, or a clone without a sample from this account's library or without consent: true.
402Not enough credit for the voice or the speech: {error, code?}.

Where else

More in The agent team

Hand over a goal · Run standing agents · Run the manager · Know what ShapelessAI can do

Every capability · Docs · /llms.txt