Overview

Protoface — realtime avatar API for developers.

Protoface API 0.1.0

Create realtime avatar sessions that consume audio and produce video.

Authentication

All /v1/* endpoints require a live API key:

Authorization: Bearer sk_live_…

Keys are minted in the dashboard and are scoped to a single environment (staging or prod).

Idempotency

POST requests may include an Idempotency-Key header (any opaque string, ≤ 255 chars). Retries with the same key inside 24 hours return the first response. The header is optional — omit it and the request executes once.

Errors

Every non-2xx response is a JSON body of the form:

{
  "error": {
    "type": "invalid_request",
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY..."
  }
}

Switch on error.code (stable lower_snake_case), not error.message.

Pagination

List endpoints use cursor pagination:

GET /v1/sessions?limit=20&starting_after=sess_01HXY...

Response shape:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "sess_01HXY..."
}

Information

• OpenAPI version: 3.1.0

Operations

GET

/v1/sessions

POST

/v1/sessions

GET

/v1/sessions/{session_id}

POST

/v1/sessions/{session_id}/end

GET

/v1/avatars

POST

/v1/avatars

GET

/v1/avatars/{avatar_id}

GET

/v1/usage

GET

/v1/status

Authentication

ApiKey

Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).

Security scheme type: http

Bearer format: sk_live_*