Create a Pipecat avatar media session
curl --request POST \
--url https://api.protoface.com/v1/pipecat/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"avatar_id": "<string>"
}
'import requests
url = "https://api.protoface.com/v1/pipecat/sessions"
payload = { "avatar_id": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({avatar_id: '<string>'})
};
fetch('https://api.protoface.com/v1/pipecat/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"relay": {
"audio_sample_rate": 123,
"decoded_video_format": "RGB",
"media_url": "<string>",
"protocol": "<string>",
"supports_audio_output": true,
"video_encoding": "jpeg",
"type": "websocket"
},
"session": {
"avatar_id": "av_stock_001",
"billing_surface": "api",
"created_at": "2026-05-25T19:00:00.123Z",
"first_frame_at": "2026-05-25T19:00:02.001Z",
"id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"idle_timeout_seconds": 30,
"max_duration_seconds": 600,
"metadata": {
"customer_session_id": "abc123"
},
"object": "session",
"quality": "standard",
"started_at": "2026-05-25T19:00:01.456Z",
"status": "running",
"transport": {
"audio_source": "data_stream",
"room_name": "demo-room",
"type": "livekit",
"url": "wss://my-app.livekit.cloud"
},
"usage": {
"billable_seconds": 12,
"frames": 300
}
},
"object": "pipecat.session"
}{
"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"
}
}{
"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"
}
}Realtime sessions
Create a Pipecat avatar media session
Start a Protoface avatar session for Pipecat. The response contains short-lived WebSocket media credentials used by the pipecat-protoface package.
Create a Pipecat avatar media session
curl --request POST \
--url https://api.protoface.com/v1/pipecat/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"avatar_id": "<string>"
}
'import requests
url = "https://api.protoface.com/v1/pipecat/sessions"
payload = { "avatar_id": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({avatar_id: '<string>'})
};
fetch('https://api.protoface.com/v1/pipecat/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"relay": {
"audio_sample_rate": 123,
"decoded_video_format": "RGB",
"media_url": "<string>",
"protocol": "<string>",
"supports_audio_output": true,
"video_encoding": "jpeg",
"type": "websocket"
},
"session": {
"avatar_id": "av_stock_001",
"billing_surface": "api",
"created_at": "2026-05-25T19:00:00.123Z",
"first_frame_at": "2026-05-25T19:00:02.001Z",
"id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"idle_timeout_seconds": 30,
"max_duration_seconds": 600,
"metadata": {
"customer_session_id": "abc123"
},
"object": "session",
"quality": "standard",
"started_at": "2026-05-25T19:00:01.456Z",
"status": "running",
"transport": {
"audio_source": "data_stream",
"room_name": "demo-room",
"type": "livekit",
"url": "wss://my-app.livekit.cloud"
},
"usage": {
"billable_seconds": 12,
"frames": 300
}
},
"object": "pipecat.session"
}{
"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"
}
}{
"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).
Body
application/json
Start request for a Pipecat avatar media session.
Stable av_... avatar id.
Required range:
1 <= x <= 600Required range:
1 <= x <= 3600Show child attributes
Show child attributes
Output quality tier.
Available options:
mock, lite, standard, pro Allowed value:
"websocket"Response
Successful Response
Pipecat avatar media session.
Short-lived direct media connection details for the Pipecat plugin.
Show child attributes
Show child attributes
Public session resource — what GET /v1/sessions/{id} returns.
Show child attributes
Show child attributes
Example:
{ "avatar_id": "av_stock_001", "billing_surface": "api", "created_at": "2026-05-25T19:00:00.123Z", "first_frame_at": "2026-05-25T19:00:02.001Z", "id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR", "idle_timeout_seconds": 30, "max_duration_seconds": 600, "metadata": { "customer_session_id": "abc123" }, "object": "session", "quality": "standard", "started_at": "2026-05-25T19:00:01.456Z", "status": "running", "transport": { "audio_source": "data_stream", "room_name": "demo-room", "type": "livekit", "url": "wss://my-app.livekit.cloud" }, "usage": { "billable_seconds": 12, "frames": 300 } }
Allowed value:
"pipecat.session"
