Browse the docs
Developers / Docs / Templates
List characters
Lists the user's saved AI Story characters (the Characters page): name, what they look like, their picture and voice. Pass an id as characters[].characterId to create_ai_story_video so the story draws them the same in every scene.
Paste it into any AI assistant. The shortcuts open with the prompt typed in; nothing is sent until you press enter.
At a glance
- REST
GET https://api.clippie.ai/v1/characters
- MCP tool
list_characters
- Scope
read
- Cost
- Free. Works with a read-only key.
Parameters
limit- In:
- query
- Type:
- integer
- Required:
- No
- Description:
- How many to return, 1-100. Default 25. 1-100.
cursor- In:
- query
- Type:
- string
- Required:
- No
- Description:
nextCursorfrom the previous page. Up to 500 chars.
Example
curl
curl "https://api.clippie.ai/v1/characters" \
-H "Authorization: Bearer $CLIPPIE_API_KEY"list-characters.mjs
const auth = { Authorization: `Bearer ${process.env.CLIPPIE_API_KEY}` };
const res = await fetch('https://api.clippie.ai/v1/characters', { headers: auth });
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());Response
200 { data, nextCursor }. Pass nextCursor as cursor for the next page. The item shape is in the OpenAPI spec.
From an MCP client
Your AI calls list_characters with the same fields as JSON arguments. See MCP server to connect one.
tools/call
{
"name": "list_characters",
"arguments": {}
}