Clippie AI logo
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:
    nextCursor from the previous page. Up to 500 chars.

Example

curl
curl "https://api.clippie.ai/v1/characters" \
  -H "Authorization: Bearer $CLIPPIE_API_KEY"

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": {}
}