Skip to main content
POST
https://jwhite.tail8bf327.ts.net
/
api
/
v1
/
avatars
/
upload
Upload Avatar
curl --request POST \
  --url https://jwhite.tail8bf327.ts.net/api/v1/avatars/upload \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "voice_id": "<string>"
}
'
{
  "id": 10,
  "name": "Professional Business Avatar",
  "url": "https://res.cloudinary.com/agenthuman/image/upload/v1234567890/avatars/xyz123.png",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "cloudinary_id": "avatars/xyz123"
}

​
Authentication

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

​
Request Body

This endpoint accepts multipart/form-data.
​
file
file
required
Avatar image or video file to upload
​
name
string
required
Avatar name
​
voice_id
string
Voice ID to associate with this avatar (e.g., ElevenLabs voice ID)

​
Request

const formData = new FormData();
formData.append('file', avatarFile); // File object from input
formData.append('name', 'Professional Business Avatar');
formData.append('voice_id', '21m00Tcm4TlvDq8ikWAM');

const response = await fetch('https://jwhite.tail8bf327.ts.net/api/v1/avatars/upload', {
  method: 'POST',
  headers: {
    'x-api-key': 'ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    // Note: Don't set Content-Type, browser will set it automatically with boundary
  },
  body: formData
});
const data = await response.json();

​
Response

{
  "id": 10,
  "name": "Professional Business Avatar",
  "url": "https://res.cloudinary.com/agenthuman/image/upload/v1234567890/avatars/xyz123.png",
  "voice_id": "21m00Tcm4TlvDq8ikWAM",
  "cloudinary_id": "avatars/xyz123"
}

{
  "error": "No file uploaded"
}

{
  "error": "name required"
}

{
  "error": "Uploaded image failed moderation checks"
}

​
Response Fields

FieldTypeDescription
idintegerUnique avatar identifier
namestringAvatar name
urlstringCloudinary URL where the avatar is hosted
voice_idstringVoice ID associated with avatar (null if not provided)
cloudinary_idstringCloudinary public ID for the uploaded file

​
Notes

  • Files are uploaded to Cloudinary and automatically stored
  • Supported formats: images (PNG, JPG, GIF, WebP) and videos (MP4, WebM)
  • If content moderation is enabled (CLOUDINARY_MODERATION_ENFORCE=true), uploads may be rejected
  • Cloudinary automatically optimizes and transforms images
  • The returned url can be used in agent configurations
  • If the upload fails moderation, the file is automatically deleted from Cloudinary

​
Content Moderation

If the server has content moderation enabled (via AWS Rekognition or similar):
  • Uploads are automatically scanned for inappropriate content
  • Rejected uploads will return a 415 error
  • The uploaded file is removed if moderation fails

​
Error Responses

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

​
Common Errors for This Endpoint

  • 400 Bad Request - Missing required fields (file or name)
  • 401 Unauthorized - Invalid or missing API key
  • 415 Unsupported Media Type - File failed content moderation checks
  • 500 Internal Server Error - Upload failed or server error