curl -X GET "https://api.hooked.so/v1/avatar/list?type=library" \
-H "x-api-key: your_api_key_here"
const response = await fetch('https://api.hooked.so/v1/avatar/list?type=library', {
headers: {
'x-api-key': 'your_api_key_here'
}
});
const data = await response.json();
console.log(data.data.avatars);
import requests
response = requests.get(
'https://api.hooked.so/v1/avatar/list',
params={'type': 'library'},
headers={'x-api-key': 'your_api_key_here'}
)
avatars = response.json()['data']['avatars']
{
"success": true,
"data": {
"avatars": [
{
"id": "avatar_sarah_01",
"name": "Sarah",
"type": "Realistic",
"gender": "Female",
"age": "Young",
"image": "https://cdn.hooked.so/avatars/sarah-thumb.jpg",
"isHD": true,
"isPro": false,
"isNew": false,
"situation": ["Business", "Casual"],
"emotions": ["Happy", "Confident"],
"skinTone": "medium",
"isCustom": false,
"source": "library"
},
{
"id": "avatar_john_02",
"name": "John",
"type": "Realistic",
"gender": "Male",
"age": "Middle-aged",
"image": "https://cdn.hooked.so/avatars/john-thumb.jpg",
"isHD": true,
"isPro": true,
"isNew": false,
"situation": ["Business", "Professional"],
"emotions": ["Neutral", "Serious"],
"skinTone": "light",
"isCustom": false,
"source": "library"
}
],
"total": 2,
"library": 2,
"custom": 0
}
}
Resources
List Avatars
Get all available avatars (library + custom) for creating videos
GET
/
v1
/
avatar
/
list
curl -X GET "https://api.hooked.so/v1/avatar/list?type=library" \
-H "x-api-key: your_api_key_here"
const response = await fetch('https://api.hooked.so/v1/avatar/list?type=library', {
headers: {
'x-api-key': 'your_api_key_here'
}
});
const data = await response.json();
console.log(data.data.avatars);
import requests
response = requests.get(
'https://api.hooked.so/v1/avatar/list',
params={'type': 'library'},
headers={'x-api-key': 'your_api_key_here'}
)
avatars = response.json()['data']['avatars']
{
"success": true,
"data": {
"avatars": [
{
"id": "avatar_sarah_01",
"name": "Sarah",
"type": "Realistic",
"gender": "Female",
"age": "Young",
"image": "https://cdn.hooked.so/avatars/sarah-thumb.jpg",
"isHD": true,
"isPro": false,
"isNew": false,
"situation": ["Business", "Casual"],
"emotions": ["Happy", "Confident"],
"skinTone": "medium",
"isCustom": false,
"source": "library"
},
{
"id": "avatar_john_02",
"name": "John",
"type": "Realistic",
"gender": "Male",
"age": "Middle-aged",
"image": "https://cdn.hooked.so/avatars/john-thumb.jpg",
"isHD": true,
"isPro": true,
"isNew": false,
"situation": ["Business", "Professional"],
"emotions": ["Neutral", "Serious"],
"skinTone": "light",
"isCustom": false,
"source": "library"
}
],
"total": 2,
"library": 2,
"custom": 0
}
}
Overview
This endpoint returns all avatars available to your account, including both the Hooked library avatars and any custom avatars you’ve created.Query Parameters
string
default:"all"
Filter avatars by type:
library: Only library avatars from Hookedcustom: Only custom avatars created by your teamall: Both library and custom avatars (default)
integer
default:"50"
Page size. Maximum
100.integer
default:"0"
Number of rows to skip. Combine with
limit to page through the list; you are done when offset + limit >= total.Response
boolean
Indicates if the request was successful
object
Show data
Show data
array
Array of avatar objects
Show avatar
Show avatar
string
Unique identifier for the avatar
string
Avatar display name
string
Avatar type (AI or Realistic)
string
Avatar gender (Male, Female, or Non-binary)
string
Age category (Young, Middle-aged, Senior)
string
URL of the avatar image (every video is generated from it)
boolean
Whether this is a custom avatar
boolean
Whether this avatar requires a Pro plan
boolean
Whether this avatar supports HD quality
number
Total number of avatars returned
number
Number of library avatars
number
Number of custom avatars
curl -X GET "https://api.hooked.so/v1/avatar/list?type=library" \
-H "x-api-key: your_api_key_here"
const response = await fetch('https://api.hooked.so/v1/avatar/list?type=library', {
headers: {
'x-api-key': 'your_api_key_here'
}
});
const data = await response.json();
console.log(data.data.avatars);
import requests
response = requests.get(
'https://api.hooked.so/v1/avatar/list',
params={'type': 'library'},
headers={'x-api-key': 'your_api_key_here'}
)
avatars = response.json()['data']['avatars']
{
"success": true,
"data": {
"avatars": [
{
"id": "avatar_sarah_01",
"name": "Sarah",
"type": "Realistic",
"gender": "Female",
"age": "Young",
"image": "https://cdn.hooked.so/avatars/sarah-thumb.jpg",
"isHD": true,
"isPro": false,
"isNew": false,
"situation": ["Business", "Casual"],
"emotions": ["Happy", "Confident"],
"skinTone": "medium",
"isCustom": false,
"source": "library"
},
{
"id": "avatar_john_02",
"name": "John",
"type": "Realistic",
"gender": "Male",
"age": "Middle-aged",
"image": "https://cdn.hooked.so/avatars/john-thumb.jpg",
"isHD": true,
"isPro": true,
"isNew": false,
"situation": ["Business", "Professional"],
"emotions": ["Neutral", "Serious"],
"skinTone": "light",
"isCustom": false,
"source": "library"
}
],
"total": 2,
"library": 2,
"custom": 0
}
}
Use Cases
Filter by gender and age
Filter by gender and age
While the API doesn’t support direct gender/age filtering, you can filter the results client-side:
const youngFemaleAvatars = data.avatars.filter(
avatar => avatar.gender === 'Female' && avatar.age === 'Young'
);
Find HD avatars
Find HD avatars
Get only avatars that support HD quality:
const hdAvatars = data.avatars.filter(avatar => avatar.isHD);
Check Pro requirements
Check Pro requirements
Identify which avatars require a Pro subscription:
pro_avatars = [a for a in avatars if a['isPro']]
free_avatars = [a for a in avatars if not a['isPro']]
Notes
Custom avatars require processing time after creation. Only avatars with
status: 2 (completed) are included in the list.Cache avatar lists for better performance. Avatar libraries don’t change frequently, so you can safely cache this data for 24 hours.