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

# Real-time voice stream

> Open a WebSocket to moderate live voice audio in real time and receive a verdict per spoken utterance.

Moderate live voice and call audio over a WebSocket. You send a `start` frame, stream `media` frames as audio arrives, then `stop`; the server transcribes speech and returns a moderation verdict for each finalized utterance.

For the full walkthrough and code examples, see [Real-time voice](/content-moderation/real-time-voice).


## OpenAPI

````yaml GET /stream
openapi: 3.1.0
info:
  title: Moderation API
  description: API for automated content moderation
  version: 1.1.0
servers:
  - url: https://api.moderationapi.com/v1
security: []
tags:
  - name: Actions
  - name: Queues
  - name: Webhooks
  - name: Wordlist
  - name: UserReports
  - name: Voice
    description: Real-time voice moderation over WebSocket.
externalDocs:
  url: https://docs.moderationapi.com
paths:
  /stream:
    get:
      tags:
        - Voice
      summary: Real-time voice moderation stream (WebSocket)
      description: >-
        Open a WebSocket to moderate live voice/call audio in real time. Speech
        is transcribed and each finalized utterance is moderated by your enabled
        text policies; you receive a verdict per utterance as it's spoken.


        **This is a WebSocket upgrade, not a regular HTTP call.** The request
        body below documents the frames you *send* over the socket; the `101`
        response documents the events you *receive*.


        - **Auth:** `Authorization: Bearer <api_key>` on the upgrade. A
        missing/invalid key closes `4401`; voice not enabled on the plan/channel
        closes `4403`.

        - **Subprotocol:** request `moderationapi.v1`.

        - **Flow:** send one `start` frame, then `media` frames as audio
        arrives, then `stop` (or disconnect). You receive `session.started`,
        `utterance.final` per utterance, optional `utterance.partial`/`warning`,
        and `session.ended`.

        - **Close codes:** `1000` normal · `1011` server error · `4400` bad
        request · `4401` auth failed · `4403` voice not enabled · `4429`
        concurrency limit.


        See the [Real-time voice
        guide](https://docs.moderationapi.com/content-moderation/real-time-voice)
        for the full walkthrough and code examples.
      parameters:
        - name: Authorization
          in: header
          required: true
          description: Bearer <api_key>
          schema:
            type: string
        - name: Sec-WebSocket-Protocol
          in: header
          required: true
          description: Requested subprotocol.
          schema:
            type: string
            enum:
              - moderationapi.v1
      requestBody:
        description: Frames sent by the client over the socket (not an HTTP body).
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/VoiceStartFrame'
                - $ref: '#/components/schemas/VoiceMediaFrame'
                - $ref: '#/components/schemas/VoiceStopFrame'
              discriminator:
                propertyName: event
      responses:
        '101':
          description: >-
            Switching Protocols. The server then streams event frames over the
            socket; the key one is `utterance.final`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/VoiceSessionStarted'
                  - $ref: '#/components/schemas/VoiceUtteranceFinal'
                  - $ref: '#/components/schemas/VoiceSessionEnded'
                discriminator:
                  propertyName: event
      servers:
        - url: wss://voice.moderationapi.com/v1
          description: Voice streaming gateway
components:
  schemas:
    VoiceStartFrame:
      type: object
      description: >-
        First frame the client sends. Declares the conversation, audio format,
        and tracks.
      required:
        - event
        - mediaFormat
        - tracks
      properties:
        event:
          type: string
          enum:
            - start
        conversationId:
          type: string
          description: >-
            Your external conversation id. Omit to have one generated and
            returned in `session.started`.
        channel:
          type: string
          description: Optional. Selects which channel's policy configuration applies.
        mediaFormat:
          type: object
          required:
            - encoding
            - sampleRate
          properties:
            encoding:
              type: string
              description: >-
                audio/x-mulaw (PCMU), audio/x-alaw (PCMA), audio/l16 (linear16),
                or a common container (wav/mp3/ogg/flac).
              example: audio/x-mulaw
            sampleRate:
              type: integer
              minimum: 8000
              maximum: 48000
              example: 8000
        tracks:
          type: array
          description: One or both tracks. Stream only the track(s) you have.
          items:
            type: object
            required:
              - name
            properties:
              name:
                type: string
                enum:
                  - inbound
                  - outbound
              authorId:
                type: string
                description: Your identifier for the speaker on this track.
        emitPartials:
          type: boolean
          default: false
          description: Set true to also receive interim, non-final transcripts.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Arbitrary JSON attached to the conversation. Stored as-is and not
            interpreted by moderation.
    VoiceMediaFrame:
      type: object
      description: Audio chunk for one track.
      required:
        - event
        - media
      properties:
        event:
          type: string
          enum:
            - media
        media:
          type: object
          required:
            - track
            - payload
          properties:
            track:
              type: string
              enum:
                - inbound
                - outbound
            payload:
              type: string
              description: Base64-encoded audio in the declared format.
    VoiceStopFrame:
      type: object
      description: Ends the call gracefully (or just disconnect).
      required:
        - event
      properties:
        event:
          type: string
          enum:
            - stop
    VoiceSessionStarted:
      type: object
      description: Sent after the start frame is accepted.
      required:
        - v
        - event
        - sessionId
        - tracks
      properties:
        v:
          type: integer
          enum:
            - 1
        event:
          type: string
          enum:
            - session.started
        conversationId:
          type: string
        sessionId:
          type: string
        tracks:
          type: array
          items:
            type: string
    VoiceUtteranceFinal:
      type: object
      description: >-
        A finalized utterance with its moderation result. The
        evaluation/recommendation/policies match the standard moderation
        response.
      required:
        - v
        - event
        - contentId
        - track
        - text
        - recommendation
      properties:
        v:
          type: integer
          enum:
            - 1
        event:
          type: string
          enum:
            - utterance.final
        conversationId:
          type: string
        contentId:
          type: string
        track:
          type: string
          enum:
            - inbound
            - outbound
        authorId:
          type: string
        text:
          type: string
        startMs:
          type: integer
        endMs:
          type: integer
        sttConfidence:
          type: number
        evaluation:
          type: object
          additionalProperties: true
        recommendation:
          type: object
          properties:
            action:
              type: string
              enum:
                - allow
                - review
                - reject
        policies:
          type: array
          items:
            type: object
            additionalProperties: true
    VoiceSessionEnded:
      type: object
      description: Sent when the call ends, with summary stats.
      required:
        - v
        - event
        - stats
      properties:
        v:
          type: integer
          enum:
            - 1
        event:
          type: string
          enum:
            - session.ended
        conversationId:
          type: string
        sessionId:
          type: string
        stats:
          type: object
          properties:
            durationMs:
              type: integer
            utterances:
              type: integer
            actions:
              type: object
              properties:
                allow:
                  type: integer
                review:
                  type: integer
                reject:
                  type: integer

````