HTTP API Reference

Relevant source files

The following files were used as context for generating this wiki page:

• wikispeech_server/wikispeech.py
• wikispeech_server/test_api.py
• wikispeech_server/options.py
• wikispeech_server/templates/usage.html
• wikispeech_simple_player.js
• workflow_demo/test_workflow.js

The Wikispeech server provides a set of HTTP endpoints for Text-to-Speech (TTS) synthesis, text processing, and system status. The API is designed to support multiple languages and configurable processing pipelines through a modular adapter architecture. It serves as a middle layer between client applications and backend speech services like MaryTTS, Piper, or Matcha.

Sources: wikispeech_server/wikispeech.py:65-72, wikispeech_server/options.py:5-10

Core API Endpoints

1. Unified Synthesis (/ or /wikispeech)

This is the primary endpoint for converting text or SSML into speech audio and timing information. It orchestrates both the text processing and the voice synthesis stages.

• Methods: GET, POST
• Parameters:

Parameter	Type	Required	Description
input	string	Yes	The text or SSML content to be synthesised.
lang	string	Yes	ISO 639-1 code (e.g., 'en', 'sv').
input_type	string	No	Type of input: text (default), ssml, or ipa.
output_type	string	No	Type of output: json (default) or html.
textprocessor	string	No	Name of a specific textprocessor configuration.
voice	string	No	Name of a specific voice configuration.

Sources: wikispeech_server/wikispeech.py:210-230, wikispeech_server/options.py:11-45

The following diagram illustrates the request flow through the unified endpoint:

2. Text Processing (/textprocessing/)

Exposes the internal text processing pipeline independently. This is used to convert raw text into a tokenized structure (markup) containing linguistic information.

• Methods: GET, POST
• Parameters: Similar to the unified endpoint, but excludes synthesis-specific options like voice.

Sources: wikispeech_server/wikispeech.py:365-385, wikispeech_server/options.py:65-90

3. Synthesis Pipeline (/synthesis/)

Exposes the synthesis stage independently. It expects input in the "markup" format generated by the text processing stage.

• Methods: GET, POST
• Input: A JSON object representing the tokenized text structure.

Sources: wikispeech_server/wikispeech.py:530-550, wikispeech_server/options.py:115-140

System Information Endpoints

The API provides metadata endpoints to help clients discover supported capabilities.

Endpoint	Method	Description
/ping	GET	Returns "wikispeech" to verify server availability.
/version	GET	Returns build info, git release, and startup timestamp.
/languages	GET	Lists all languages supported by both textproc and synthesis.
/default_voices	GET	Returns default processor and voice for each language.
/synthesis/voices	GET	Lists all loaded voice configurations.
/options	OPTIONS	Returns JSON schema describing parameters for /.

Sources: wikispeech_server/wikispeech.py:80-155, wikispeech_server/test_api.py:25-40

Data Structures

JSON Markup (Textprocessing Output)

The output of the text processing stage is a nested structure of paragraphs, sentences, and tokens.

{
  "lang": "en-US",
  "paragraphs": [
    {
      "sentences": [
        {
          "phrases": [
            {
              "tokens": [
                {
                  "token_orth": "test",
                  "words": [
                    {
                      "orth": "test",
                      "trans": "' t E s t",
                      "pos": "NN"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Sources: wikispeech_server/test_api.py:145-155, workflow_demo/test_workflow.js:335-365

Synthesis Response

The final response contains the audio data and token timing information required for "read-along" highlighting.

• audio: URL to the generated Opus file.
• audio_data: Base64 encoded audio content (if configured).
• tokens: List of tokens with orth (orthography) and endtime (in milliseconds).

Sources: wikispeech_server/wikispeech.py:615-635, wikispeech_simple_player.js:155-180

Integration Proxies

Lexicon Server Proxy (/lexserver/)

The Wikispeech server acts as a proxy to a separate lexicon service, allowing clients to query and update word transcriptions without cross-origin issues.

• Lookup: /lexserver/lexicon/lookup?lexicons=NAME&words=WORD
• Validation: /lexserver/validation/validateentry
• Update: /lexserver/lexicon/updateentry

Sources: wikispeech_server/wikispeech.py:680-690, workflow_demo/test_workflow.js:450-480

Audio Server (/audio/)

Serves temporary audio files generated during synthesis from the audio_tmpdir directory.

Sources: wikispeech_server/wikispeech.py:645-655

Conclusion

The Wikispeech HTTP API provides a structured interface for complex TTS workflows. By separating text processing from synthesis and offering discovery endpoints, it enables flexible integration for web-based speech applications and editor tools. Its ability to return fine-grained timing information alongside audio makes it particularly suited for interactive educational and accessibility features.