Skip to main content
GET
/
v1
/
avatars
# List realistic avatars
curl "https://api.vibepeak.ai/v1/avatars?type=realistic" \
  -H "Authorization: Bearer vpk_live_xxxxx"

# List custom avatars with pagination
curl "https://api.vibepeak.ai/v1/avatars?type=custom&limit=10&offset=0" \
  -H "Authorization: Bearer vpk_live_xxxxx"

{
  "avatars": [
    {
      "id": "e225efd4-f936-4a01-b56a-bb3ab30c2cbd",
      "name": "Sarah",
      "type": "realistic",
      "image_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.jpg",
      "video_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.mp4"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Michael",
      "type": "realistic",
      "image_url": "https://storage.vibepeak.ai/avatars/michael-thumb.jpg",
      "video_url": "https://storage.vibepeak.ai/avatars/michael-thumb.mp4"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
Retrieves a paginated list of avatars. You can request either realistic (public) avatars available to all users, or your custom avatars.

​
Query Parameters

​
type
string
required
The type of avatars to retrieve.Allowed values: realistic, custom
  • realistic: Public avatars available to all users
  • custom: Your custom avatars (uploaded or AI-generated)
​
limit
integer
default:"20"
Maximum number of avatars to return per page.Range: 1-100
​
offset
integer
default:"0"
Number of avatars to skip (for pagination).Minimum: 0

​
Response

​
avatars
array
required
List of avatar objects.
​
pagination
object
required
Pagination information.
# List realistic avatars
curl "https://api.vibepeak.ai/v1/avatars?type=realistic" \
  -H "Authorization: Bearer vpk_live_xxxxx"

# List custom avatars with pagination
curl "https://api.vibepeak.ai/v1/avatars?type=custom&limit=10&offset=0" \
  -H "Authorization: Bearer vpk_live_xxxxx"

{
  "avatars": [
    {
      "id": "e225efd4-f936-4a01-b56a-bb3ab30c2cbd",
      "name": "Sarah",
      "type": "realistic",
      "image_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.jpg",
      "video_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.mp4"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Michael",
      "type": "realistic",
      "image_url": "https://storage.vibepeak.ai/avatars/michael-thumb.jpg",
      "video_url": "https://storage.vibepeak.ai/avatars/michael-thumb.mp4"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

​
Usage with Video Creation

Once you’ve retrieved the avatar list, use the avatar id when creating videos: 
// 1. List available avatars
const avatarsResponse = await fetch('https://api.vibepeak.ai/v1/avatars?type=realistic', {
  headers: { 'Authorization': 'Bearer vpk_live_xxxxx' }
});
const { avatars } = await avatarsResponse.json();

// 2. Select an avatar and create a video
const selectedAvatar = avatars[0];

const videoResponse = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: ['https://example.com/image1.jpg', /* ... */],
    script: 'Welcome to this beautiful property...',
    voice: { voice_id: 'voice-123' },
    style: 'do-not-modify',
    avatar_id: selectedAvatar.id  // Use the avatar ID here
  })
});

​
Error Codes

CodeStatusDescription
MISSING_PARAMETER400Required type parameter is missing
INVALID_PARAMETER400Invalid value for type, limit, or offset
VALIDATION_ERROR400Query parameter validation failed
INVALID_API_KEY401Invalid or missing API key
See Error Handling for more details.