> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protoface.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete an avatar

> Delete a custom avatar and permanently remove its uploaded source image and built assets. The avatar disappears from listings and can no longer run sessions; past session and usage records are kept. Platform stock avatars cannot be deleted.



## OpenAPI

````yaml /openapi.json delete /v1/avatars/{avatar_id}
openapi: 3.1.0
info:
  description: >
    Create realtime avatar sessions.


    ### 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 /v1/sessions` 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.


    ### Errors

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


    ```json

    {
      "error": {
        "type": "invalid_request",
        "code": "transport.unsupported",
        "message": "transport.type=pipecat is not supported",
        "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:


    ```json

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

    ```
  summary: Protoface — realtime avatar API for developers.
  title: Protoface API
  version: 0.1.0
servers: []
security: []
tags:
  - description: >-
      Create, retrieve, list, and end realtime avatar sessions. Sessions stream
      audio in and video out; their lifecycle drives billing.
    name: sessions
  - description: >-
      Avatar definitions. Includes platform stock avatars and customer-uploaded
      avatars.
    name: avatars
  - description: Blocking talking-avatar video generation from uploaded audio.
    name: videos
  - description: Aggregate usage for billing reconciliation.
    name: usage
  - description: >-
      Public platform metadata — currently just status. Unauthenticated.
      Internal load-balancer and task health probes exist on this host but are
      not part of the documented surface.
    name: platform
  - description: Direct media sessions for the `pipecat-protoface` avatar video service.
    name: pipecat
  - description: Public billing plan metadata for signup and pricing UI.
    name: billing
paths:
  /v1/avatars/{avatar_id}:
    delete:
      tags:
        - avatars
      summary: Delete an avatar
      description: >-
        Delete a custom avatar and permanently remove its uploaded source image
        and built assets. The avatar disappears from listings and can no longer
        run sessions; past session and usage records are kept. Platform stock
        avatars cannot be deleted.
      operationId: delete_avatar
      parameters:
        - description: Stable `av_…` avatar id.
          in: path
          name: avatar_id
          required: true
          schema:
            description: Stable `av_…` avatar id.
            title: Avatar Id
            type: string
      responses:
        '204':
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
          description: Platform avatars are not deletable.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
          description: Missing or invalid API key.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
          description: No avatar with that id.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
          description: Request body or parameters failed validation.
      security:
        - ApiKey: []
components:
  schemas:
    ApiErrorEnvelope:
      additionalProperties: false
      description: Wire format for every non-2xx public API response.
      examples:
        - error:
            code: transport.unsupported
            message: transport.type=pipecat is not supported
            param: transport.type
            request_id: req_01HXY5K8E7QYG3X8Z6N9R7S0VR
            type: invalid_request
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - error
      title: ApiErrorEnvelope
      type: object
    ApiError:
      additionalProperties: false
      description: Concrete error returned inside `ApiErrorEnvelope.error`.
      properties:
        code:
          description: >-
            Stable machine-readable subcode (lower_snake_case). SDKs should
            switch on this, not `message`.
          type: string
        message:
          description: Human-readable summary. Not stable; do not parse.
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          description: Offending request field (dot-path), if applicable.
        request_id:
          description: Echo of the `X-Request-Id` response header for support.
          type: string
        type:
          $ref: '#/components/schemas/ErrorType'
      required:
        - type
        - code
        - message
        - request_id
      title: ApiError
      type: object
    ErrorType:
      description: |-
        Top-level error categories. Maps roughly to HTTP status.

        `code` (a free-form lower_snake_case string on `ApiError`) is the
        machine-readable subcode SDKs should switch on; `type` is the broad
        category.
      enum:
        - invalid_request
        - authentication
        - permission
        - not_found
        - conflict
        - unprocessable
        - rate_limit
        - quota_exceeded
        - internal
        - service_unavailable
      title: ErrorType
      type: string
  securitySchemes:
    ApiKey:
      bearerFormat: sk_live_*
      description: >-
        Live API key minted in the dashboard. Pass as `Authorization: Bearer
        sk_live_…`. Keys are scoped to a single environment (staging / prod).
      scheme: bearer
      type: http

````