Skip to main content
GET
https://api.agenthuman.com
/
v1
/
avatars
/
public
List Public Avatars
curl --request GET \
  --url https://api.agenthuman.com/v1/avatars/public \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "avatars": [
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W6V",
      "name": "Professional Business Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar5.png",
      "is_favorite": 0,
      "is_public": 1,
      "created_at": "2024-01-10T14:00:00Z",
      "updated_at": "2024-01-10T14:00:00Z"
    },
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W7X",
      "name": "Casual Friendly Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar6.png",
      "is_favorite": 1,
      "is_public": 1,
      "created_at": "2024-01-09T10:00:00Z",
      "updated_at": "2024-01-09T10:00:00Z"
    }
  ]
}

​
Response

​
success
boolean
Whether the request was successful
​
avatars
array
Array of public avatar objects (See Avatar schema).
{
  "success": true,
  "avatars": [
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W6V",
      "name": "Professional Business Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar5.png",
      "is_favorite": 0,
      "is_public": 1,
      "created_at": "2024-01-10T14:00:00Z",
      "updated_at": "2024-01-10T14:00:00Z"
    },
    {
      "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W7X",
      "name": "Casual Friendly Avatar",
      "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar6.png",
      "is_favorite": 1,
      "is_public": 1,
      "created_at": "2024-01-09T10:00:00Z",
      "updated_at": "2024-01-09T10:00:00Z"
    }
  ]
}

​
Important Notes

  • Returns up to 100 public avatars
  • Avatars are ordered by creation date (newest first)
  • The is_favorite field reflects whether you have favorited the avatar
  • This endpoint returns public characters (top-level avatars where parent_id = null)
  • To create a session, you must use a look. After selecting a character, fetch its looks via GET /v1/avatars?parent_id=<character_avatar_id>.
  • Authentication is still required (API key or JWT), even for public avatars