curl --request GET \
--url https://api.protoface.com/v1/avatars/{avatar_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.protoface.com/v1/avatars/{avatar_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.protoface.com/v1/avatars/{avatar_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"created_at": "2026-01-01T00:00:00Z",
"id": "av_stock_001",
"is_demo": true,
"name": "Stock Avatar 001",
"object": "avatar",
"runtime_type": "avtr1",
"status": "ready",
"voice": "cedar"
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}Retrieve an avatar
Return a single avatar by id.
curl --request GET \
--url https://api.protoface.com/v1/avatars/{avatar_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.protoface.com/v1/avatars/{avatar_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.protoface.com/v1/avatars/{avatar_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"created_at": "2026-01-01T00:00:00Z",
"id": "av_stock_001",
"is_demo": true,
"name": "Stock Avatar 001",
"object": "avatar",
"runtime_type": "avtr1",
"status": "ready",
"voice": "cedar"
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}Authorizations
Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).
Path Parameters
Stable av_… avatar id.
Response
Successful Response
Public Avatar resource returned by GET /v1/avatars and GET /v1/avatars/{id}.
Stable av_… avatar id. Platform stock avatars use fixed ids such as av_stock_001; customer avatars use generated ids.
True for platform stock avatars (e.g. av_stock_001).
Runtime that serves this avatar (e.g. mock, avtr1).
Lifecycle of a custom avatar.
ready — usable for sessions.
processing — being fitted / converted.
failed — fitting failed; will not be usable without re-upload.
ready, processing, failed Preferred managed-conversation instructions for this avatar, when configured.
Human-readable reason the build failed (e.g. No face detected in source image.). Only set while status is failed.
True when this avatar was created directly from a customer photo upload, rather than from a stock or reused face.
"avatar"Preferred conversation voice for this avatar, when configured.
Voice-style instructions for managed conversations using this avatar.

