openapi: 3.0.3
info:
  title: Texto Fala
  description: |-
    A versão 2 da API REST contém métodos que realizam a síntese de fala utilizando streaming. Isso significa que o áudio começa a ser entregue à aplicação assim que o processo de síntese é iniciado. O stream de áudio já pode então ser reproduzido, mesmo antes do áudio ser totalmente sintetizado.

    Além disso, a versão 2 oferece métodos de apoio que permitem consultar os encoders e vozes disponiveis, facilitando a criação de aplicações.
  contact:
    email: suporte-textofala@cpqd.com.br
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 2.0.0
externalDocs:
  description: Documentação do Texto Fala
  url: https://speechweb.cpqd.com.br/tts/docs/latest/
servers:
  - url: https://speech.cpqd.com.br/tts-demo/rest/v2
tags:
  - name: tts
    description: Síntese de fala neural do CPQD
    externalDocs:
      description: Documentação do produto
      url: https://speechweb.cpqd.com.br/tts-neural/
paths:
  /synthesize:
    get:
      tags:
        - tts
      summary: Converte texto em fala
      description: Converte texto em fala
      operationId: synthesizeGet
      security:
        - TokenAuth: []
      parameters:
        - name: text
          in: query
          description: O texto a ser convertido em fala. O conteúdo deve ser texto em UTF-8 ou ISO-8859-1 e estar codificado em URL Encode.
          required: true
          explode: true
          schema:
            type: string
        - name: voice
          in: query
          description: Nome da voz.
          required: false
          explode: true
          schema:
            type: string
        - name: encoder
          in: query
          description: Nome do encoder utilizado para gerar o áudio de saída.
          required: false
          explode: true
          schema:
            type: string
        - name: volume
          in: query
          description: Volume global do áudio de saída.
          required: false
          explode: true
          schema:
            type: number
            default: 1.0
            maximum: 2.0
            minimum: 0.0
        - name: rate
          in: query
          description: Velocidade ou ritmo da fala.
          required: false
          explode: true
          schema:
            type: number
            default: 1.0
            maximum: 3.0
            minimum: 0.3
        - name: filename
          in: query
          description: Nome do arquivo que será baixado. Navegadores ou ferramentas utilizarão este nome por padrão.
          required: false
          explode: true
          schema:
            type: string
            deprecated: true
        - name: use_streaming
          in: query
          description: Uso de síntese via streaming.
          required: false
          explode: true
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Síntese realizada com sucesso.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Parâmetro de entrada inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '401':
          description: Usuário não autenticado
        '403':
          description: Usuário não está autorizado para usar este endpoint.
        '500':
          description: Erro na operação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'

    post:
      tags:
        - tts
      summary: Converte texto em fala
      description: Converte texto em fala
      operationId: synthesizePost
      security:
        - TokenAuth: []
      requestBody:
        description: Solicita a síntese de fala do texto informado.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynthesizeRequest'
        required: true
      responses:
        '200':
          description: Síntese realizada com sucesso.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            audio/x-wav:
              schema:
                type: string
                format: binary
            audio/mp3:
              schema:
                type: string
                format: binary
        '400':
          description: Parâmetro de entrada inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '401':
          description: Usuário não autenticado
        '403':
          description: Usuário não está autorizado para usar este endpoint.
        '500':
          description: Erro na operação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'

  /synthesize/ssml:
    post:
        tags:
          - tts
        summary: Converte documento SSML em fala
        description: Converte documento SSML em fala
        operationId: synthesizeSSMLPost
        security:
          - TokenAuth: []
        parameters:
          - name: X-Encoder
            in: header
            description: Nome do encoder utilizado para gerar o áudio de saída.
            required: false
            explode: true
            schema:
              type: string
          - name: X-Volume
            in: header
            description: Volume global do áudio de saída.
            required: false
            explode: true
            schema:
              type: number
              default: 1.0
              maximum: 2.0
              minimum: 0.0
          - name: X-Rate
            in: header
            description: Velocidade ou ritmo da fala.
            required: false
            explode: true
            schema:
              type: number
              default: 1.0
              maximum: 3.0
              minimum: 0.3
          - name: X-Account-Tag
            in: header
            description: Indica o utilizador. Esse campo pode ser utilizado para discriminar o consumo de uma equipe, cenário de uso ou subcliente.
            required: false
            explode: true
            schema:
              type: string
          - name: X-Use-Streaming
            in: header
            description: Uso de síntese via streaming.
            required: false
            explode: true
            schema:
              type: boolean
              default: false
        requestBody:
          description: Conteúdo SSML.
          required: true
          content:
            application/ssml+xml:
                schema:
                    $ref: 'https://www.w3.org/TR/speech-synthesis11/synthesis.xsd'
            application/xml:
                schema:
                    $ref: 'https://www.w3.org/TR/speech-synthesis11/synthesis.xsd'
            text/xml:
                schema:
                    $ref: 'https://www.w3.org/TR/speech-synthesis11/synthesis.xsd'
        responses:
          '200':
            description: Síntese realizada com sucesso.
            content:
              application/octet-stream:
                schema:
                  type: string
                  format: binary
              audio/x-wav:
                schema:
                  type: string
                  format: binary
              audio/mp3:
                schema:
                  type: string
                  format: binary
          '400':
            description: Parâmetro de entrada inválido
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorInfo'
          '401':
            description: Usuário não autenticado
          '403':
            description: Usuário não está autorizado para usar este endpoint.
          '500':
            description: Erro na operação
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorInfo'

  /voices:
    get:
      tags:
        - tts
      summary: Recupera a lista de vozes disponíveis
      description: Recupera a lista de vozes disponíveis
      operationId: get_voices
      security:
        - TokenAuth: []
      responses:
        '200':
          description: Lista de vozes disponíveis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voices'
        '500':
          description: Erro na operação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'

  /encoders:
    get:
      tags:
        - tts
      summary: Recupera a lista de encoders disponíveis
      description: Recupera a lista de encoders disponíveis
      operationId: get_encoders
      responses:
        '200':
          description: Lista de encoders disponíveis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Encoders'
        '500':
          description: Erro na operação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'


components:
  securitySchemes:
    TokenAuth:
      type: http
      scheme: bearer
  schemas:
    ErrorInfo:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 10
          description: Código do erro.
        message:
          type: string
          example: Error details
          description: Mensagem descritiva do erro ocorrido.
    SynthesizeRequest:
      type: object
      properties:
        text:
          description: O texto a ser convertido em fala. O conteúdo deve ser texto em UTF-8 ou ISO-8859-1 e estar codificado em URL Encode.
          type: string
          example: Olá mundo
        voice:
          description: Nome da voz.
          type: string
          example: adriana-neutro-performance
        encoder:
          description: Nome do encoder utilizado para gerar o áudio de saída.
          type: string
          example: "wav/22050/16/1"
        volume:
          description: Volume global do áudio de saída.
          type: number
          default: 1.0
          maximum: 3.0
          minimum: 0.3
        rate:
          description: Velocidade ou ritmo da fala.
          type: number
          default: 1.0
          maximum: 3.0
          minimum: 0.3
        filename:
          description: Nome do arquivo que será baixado. Navegadores ou ferramentas utilizarão este nome por padrão.
          type: string
          example: "ola-mundo.wav"
          deprecated: true
    Voices:
      type: array
      items:
        type: object
        properties:
          name:
            description: Nome da voz.
            type: string
            example: adriana-neutro-performance
          languages:
            type: array
            items:
              type: string
            example: [pt-br]
            description: Lista de idiomas suportados pela voz.
          mode:
            description: Indica o modo de operação da voz. Vozes no modo PERFORMANCE priorizam desempenho, entregando sínteses mais rápidas, enquanto que vozes QUALITY priorizam a qualidade do áudio resultante.
            enum: [PERFORMANCE, QUALITY]
          available:
            type: boolean
            description: Indica se a voz está disponível para uso utilizando o token atual.
    Encoders:
      type: array
      items:
        type: object
        properties:
          name:
            description: Nome do encoder.
            type: string
            example: wav/22050/16/1
          codec:
            type: string
            example: RIFF PCM Linear
            description: Codec utilizado na codificação do áudio.
          sampleRate:
            description: Taxa de amostragem do áudio.
            type: integer
            format: int32
            example: 22050
          bitsPerSample:
            description: Número de bits por amostra.
            type: integer
            format: int32
            example: 16
          channels:
            type: integer
            format: int32
            description: Quantidade de canais.
