api-reference

Where to Find Supertonic API Documentation: Complete Guide for All Languages

June 13, 2026 supertone-inc/supertonic ↗

Supertonic API documentation is hosted entirely within the supertone-inc/supertonic GitHub repository, with the root README.md providing authentication and overview details, while language-specific folders contain platform-specific implementation guides.

The supertone-inc/supertonic repository maintains comprehensive Supertonic API documentation directly alongside its source code. This embedded documentation approach ensures that specifications remain synchronized with implementation details across all supported languages. Each platform-specific folder contains both narrative guides and executable code examples that demonstrate proper authentication patterns and API usage.

Main Documentation Locations

Root README Overview

The primary entry point for Supertonic API documentation is the repository's [README.md](https://github.com/supertone-inc/supertonic/blob/main/README.md). This file contains the high-level service description, authentication requirements, request/response format specifications, and links to language-specific implementations. According to the source code, this document serves as the authoritative reference for understanding the API's capabilities and security requirements.

Language-Specific Guides

Each supported language maintains its own dedicated documentation within the repository structure:

These files contain detailed usage instructions, authentication steps, and request examples specific to each platform.

Core Implementation Files

Beyond narrative documentation, the repository contains source files that demonstrate the actual API client implementations. These files serve as living documentation for the request construction patterns:

Authentication Setup

All Supertonic API documentation examples assume you have obtained an API key and configured it as an environment variable:

export SUPERTONIC_API_KEY="your_api_key_here"

Code Examples by Language

The following examples demonstrate how to call the Supertonic API using the helper functions provided in each language client. All examples synthesize the text "Hello, world!" using the en_us voice and save the output to output.wav.

Python Implementation

In py/helper.py, the synthesize function provides a Pythonic interface to the API:

import supertonic.helper as st

text = "Hello, world!"
audio = st.synthesize(text, voice="en_us")
with open("output.wav", "wb") as f:
    f.write(audio)

Node.js Implementation

The Node.js client in nodejs/helper.js exposes an async synthesize function:

const { synthesize } = require("./helper.js");

(async () => {
  const audio = await synthesize("Hello, world!", "en_us");
  require("fs").writeFileSync("output.wav", audio);
})();

Rust Implementation

The Rust implementation in rust/src/helper.rs provides error-handling through the Result type:

use supertonic::helper;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let audio = helper::synthesize("Hello, world!", "en_us")?;
    std::fs::write("output.wav", audio)?;
    Ok(())
}

Go Implementation

The Go package in go/helper.go handles API communication with explicit error checking:

package main

import (
    "log"
    "os"
    "supertonic/helper"
)

func main() {
    audio, err := helper.Synthesize("Hello, world!", "en_us")
    if err != nil {
        log.Fatal(err)
    }
    if err := os.WriteFile("output.wav", audio, 0644); err != nil {
        log.Fatal(err)
    }
}

Summary

  • Primary documentation for the Supertonic API resides in the supertone-inc/supertonic GitHub repository, specifically in the root README.md and language-specific README files.
  • Authentication requires setting the SUPERTONIC_API_KEY environment variable before running any client code.
  • Language implementations are organized into separate folders (py/, nodejs/, rust/, go/, etc.), each containing a README.md with usage instructions and a helper file (helper.py, helper.js, etc.) with the core API client logic.
  • Code examples demonstrate consistent patterns across languages: import the helper module, call synthesize with text and voice parameters, and write the returned audio bytes to a file.

Frequently Asked Questions

Is there official hosted documentation outside of GitHub?

No, according to the supertone-inc/supertonic source code, all official Supertonic API documentation is maintained within the repository itself. The root README.md provides the general API overview, while each language folder contains platform-specific guides. This approach ensures documentation stays synchronized with code changes.

Which file should I read first when implementing a Python client?

Start with py/README.md for high-level setup instructions and authentication details. Then examine py/helper.py to understand the underlying implementation of the synthesize function and how it handles HTTP requests and response parsing.

How do I handle API errors in the different language clients?

Error handling patterns vary by language as shown in the source code. The Rust client in rust/src/helper.rs uses Result types with the ? operator for propagation. The Go implementation in go/helper.go returns explicit error values that must be checked. Python and Node.js implementations typically raise exceptions or reject promises on API failures.

Can I use the Supertonic API without the provided helper files?

Yes, while the helper files (helper.py, helper.js, helper.rs, etc.) provide convenient wrappers, you can implement direct HTTP calls by following the request/response format specifications detailed in the root README.md. The helper files serve as reference implementations for constructing proper API requests.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →