Skip to main content
GET
https://api.agenthuman.com
/
v1
/
avatars
List My Avatars
curl --request GET \
  --url https://api.agenthuman.com/v1/avatars \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "avatars": [
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "name": "Professional Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1.png",
      "parent_id": null,
      "looks_count": 3,
      "is_favorite": 1,
      "is_public": 0,
      "active": 1,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W5U",
      "name": "Professional Avatar (Look 1)",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1-look.png",
      "parent_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "video_url": "https://res.cloudinary.com/example/video/upload/.../avatar1-look.mp4",
      "is_favorite": 0,
      "is_public": 0,
      "active": 1,
      "created_at": "2024-01-14T09:20:00Z",
      "updated_at": "2024-01-14T09:20:00Z"
    }
  ]
}

​
Query Parameters

​
parent_id
string
If provided, returns looks (session-ready avatars) for the given character ID.
​
characters_only
string
default:"true"
When characters_only is not false, the endpoint returns characters only (avatars with parent_id = null). Set characters_only=false to return characters and looks you have access to.
Sessions require a look. To create a session, use an avatar with parent_id set (a look). Characters (top-level avatars) cannot be used directly for sessions.

​
Response

​
success
boolean
Whether the request was successful
​
avatars
array
Array of avatar objects (See Avatar schema).
{
  "success": true,
  "avatars": [
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "name": "Professional Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1.png",
      "parent_id": null,
      "looks_count": 3,
      "is_favorite": 1,
      "is_public": 0,
      "active": 1,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W5U",
      "name": "Professional Avatar (Look 1)",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1-look.png",
      "parent_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "video_url": "https://res.cloudinary.com/example/video/upload/.../avatar1-look.mp4",
      "is_favorite": 0,
      "is_public": 0,
      "active": 1,
      "created_at": "2024-01-14T09:20:00Z",
      "updated_at": "2024-01-14T09:20:00Z"
    }
  ]
}