sangtao.ai
API key

Characters

List characters

Your characters, most recently edited first. No credits charged.

GEThttps://api.sangtao.ai/v2/characters

Authorization

  • X-Api-Keystring · headerrequired

    Your API key, from the API keys page of your account.

A character is a reusable profile for making videos, so one character keeps the same look across scenes and across videos. A profile holds a name, an appearance description, a biography, other names, and up to 3 reference images. It is used in characterIds of Motion compose and Video Studio.

The Characters endpoints cost no credits.

Query parameters

  • pageint

    Page number, from 1. Leave out page and pageSize to get everything.

  • pageSizeint

    Items per page. Default 50, at most 200. limit is accepted as the same thing.

The total, across all pages, is in the X-Total-Count header.

Response

An array of Character, most recently edited first. Each Character:

  • idstringrequired

    The character's id, ch_…. Use it in characterIds when creating a video

  • namestringrequired

    Name, required, up to 100 characters

  • appearanceDescriptionstring | null

    What the character looks like, so the AI draws it right — up to 1,000 characters. Best written in English, short, as a list of features

  • biographystring | null

    Background or personality, which helps the AI place the character in the right scenes. Up to 2,000 characters

  • aliasesstring | null

    Other names, separated by commas, up to 200 characters. Helps the AI recognise the character when the story calls it something else

  • publishStatusstring | null

    Community sharing status

    Available options:nullpendingapprovedrejected

  • createdAtstringrequired

    When it was created (ISO 8601, UTC)

  • updatedAtstringrequired

    When it was last changed (ISO 8601, UTC)

  • refImagesobject[]required

    Up to 3 reference images, in sortOrder order

    Show child attributes

    • idstringrequired

      The image's id, ci_… — the imageId of Delete a reference image

    • imageUrlstringrequired

      URL of the image

    • thumbnailUrlstring | null

      URL of a smaller copy. Can be null for a few seconds after the image is added

    • sortOrdernumberrequired

      Position among the character's images

A character can be used when creating a video if it has at least one of: a reference image, or an appearanceDescription.

Using characters when creating a video

Pass their ids in characterIds — up to 5 characters for Motion.

An id in the wrong format gets 400. The id of a character that is not yours gets 404 CHARACTER_NOT_FOUND (Motion), or is ignored (Video Studio).

GET/characters
curl "https://api.sangtao.ai/v2/characters" \
  -H "X-Api-Key: YOUR_API_KEY"
{
  "success": true,
  "data": [
    {
      "id": "ch_3kT9qPz0B",
      "name": "Mèo Mướp",
      "appearanceDescription": "orange tabby cat, chubby body, half-closed drowsy eyes, white belly patch",
      "biography": "Chú mèo lười của tiệm sách, hay ngủ trên quầy thu ngân.",
      "aliases": "Mướp, Bé Mướp",
      "publishStatus": null,
      "createdAt": "2026-11-08T09:12:44Z",
      "updatedAt": "2026-11-08T09:20:01Z",
      "refImages": [
        {
          "id": "ci_8hQ2mZr4K",
          "imageUrl": "https://…/a.png",
          "thumbnailUrl": "https://…/a_thumb.webp",
          "sortOrder": 0
        }
      ]
    }
  ]
}