Cast actors and voices
The account's actors: the founder as themself, and any character the videos are narrated or fronted by.
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.voiceDescriptionis 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.descriptiondesigns 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 listshapeless characters voice
Example
Refusals
| Status | Meaning |
|---|---|
| 400 | Not JSON, no name, or a name over 80 characters. |
| 404 | No such actor on this account. |
| 400 | Not JSON, nothing to change, or a portrait or face reference that is not in this account's library. |
| 400 | Not 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. |
| 402 | Not 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
