Skip to main content
POST
https://jwhite.tail8bf327.ts.net
/
api
/
v1
/
avatars
Create Avatar
curl --request POST \
  --url https://jwhite.tail8bf327.ts.net/api/v1/avatars \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "voice_id": "<string>"
}
'
{
  "id": 10,
  "message": "Avatar created"
}

​
Authentication

Requires an API key in the x-api-key header. 
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Request Body

​
name
string
required
Avatar name
​
url
string
required
URL to avatar image or video file (can be Cloudinary URL or any accessible URL)
​
voice_id
string
Voice ID to associate with this avatar (e.g., ElevenLabs voice ID). When an agent uses this avatar, it will use this voice.

​
Alternative: Upload Avatar

For uploading a file directly, use the Upload Avatar endpoint instead.

​
Request

POST https://jwhite.tail8bf327.ts.net/api/v1/avatars
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "name": "Professional Business Avatar",
  "url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar.png",
  "voice_id": "21m00Tcm4TlvDq8ikWAM"
}

​
Response

{
  "id": 10,
  "message": "Avatar created"
}

{
  "error": "name and url required"
}

​
Notes

  • The url field can be any accessible image or video URL
  • The voice_id is optional but recommended - it associates a voice with this avatar
  • When an agent uses this avatar, it will automatically use the avatar’s assigned voice
  • If you have a file to upload, use the Upload Avatar endpoint instead
  • The response includes the created avatar’s id which can be used in agent configurations
  • Only the authenticated user can access this avatar unless it’s marked as public

​
Error Responses

For information about error responses and status codes, see Error Responses.

​
Common Errors for This Endpoint

  • 400 Bad Request - Missing required fields (name and url are both required)
  • 401 Unauthorized - Invalid or missing API key
  • 500 Internal Server Error - Server error