openapi: 3.1.0
info:
  title: DeepL Translation Documents Voice API
  description: The DeepL API exposes machine translation, document translation, glossary management, write/improve, and usage endpoints. Both Pro and Free tiers are available, hosted on different base URLs.
  version: '2'
  contact:
    name: DeepL Developers
    url: https://developers.deepl.com/
servers:
- url: https://api.deepl.com/v2
  description: DeepL Pro
- url: https://api-free.deepl.com/v2
  description: DeepL Free
security:
- authKey: []
tags:
- name: Voice
paths:
  /voice/realtime:
    post:
      summary: Request a real-time voice session
      operationId: requestVoiceSession
      tags:
      - Voice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source_media_content_type:
                  type: string
                  description: Audio format for the source media (e.g., "audio/ogg; codecs=opus").
                message_format:
                  type: string
                  enum:
                  - json
                  - msgpack
                  default: json
                source_language:
                  type: string
                source_language_mode:
                  type: string
                  enum:
                  - auto
                  - fixed
                  default: auto
                target_languages:
                  type: array
                  maxItems: 5
                  items:
                    type: string
                target_media_languages:
                  type: array
                  maxItems: 1
                  items:
                    type: string
                target_media_content_type:
                  type: string
                target_media_voice:
                  type: string
                  enum:
                  - male
                  - female
                spoken_terms_id:
                  type: string
                  format: uuid
                glossary_id:
                  type: string
                formality:
                  type: string
                  enum:
                  - default
                  - formal
                  - more
                  - informal
                  - less
              required:
              - source_media_content_type
      responses:
        '200':
          description: Session created. Returns the WebSocket streaming URL and an ephemeral token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSession'
    get:
      summary: Reconnect to an existing real-time voice session
      operationId: reconnectVoiceSession
      tags:
      - Voice
      parameters:
      - in: query
        name: token
        required: true
        schema:
          type: string
        description: The latest ephemeral token obtained for the stream.
      responses:
        '200':
          description: Reconnect details. Returns a fresh streaming URL and token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceSession'
components:
  schemas:
    VoiceSession:
      type: object
      properties:
        streaming_url:
          type: string
          format: uri
          description: WebSocket URL for the real-time voice channel.
        token:
          type: string
          description: Ephemeral, single-use authentication token for the WebSocket connection.
        session_id:
          type: string
          format: uuid
  securitySchemes:
    authKey:
      type: apiKey
      in: header
      name: Authorization
      description: DeepL-Auth-Key <key>