HyperYap Local HTTP API

Overview

The local HTTP API allows other applications to send audio files to HyperYap for transcription without using the graphical interface. This is useful for integrating HyperYap as a backend Speech-to-Text engine in other applications.

Status: Experimental feature - API design may change in future releases.

Quick Start

Open HyperYap
Go to Settings → System
Find Local API (Experimental)
Toggle it ON
The API will start immediately on http://localhost:4800
(Optional) Change the port number if needed (default: 4800)

The API will remain running as long as HyperYap is open. It will stop when you close the application or toggle the API off in settings.

API Endpoint

POST http://localhost:4800/api/transcribe

Request

Send a multipart form with an audio file field named audio containing a .wav file:

curl -X POST http://127.0.0.1:4800/api/transcribe -F "audio=@/audio.wav;type=audio/wav"

Response

Success (200 OK):

{
    "text": "Hello everyone, here is the complete transcript..."
}

Error (4xx/5xx):

{
    "error": "Error message describing what went wrong"
}

Requirements

Audio file must be in WAV format (.wav)
File is automatically resampled to 16kHz if needed
Works best with complete sentences
Parakeet automatically detects the language (French, English, etc.)

Usage Examples

Python

import requests

with open('audio.wav', 'rb') as f:
    files = {'audio': f}
    response = requests.post('http://localhost:4800/api/transcribe', files=files)
    result = response.json()
    print(result['text'])

JavaScript/Node.js

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

async function transcribe(audioPath) {
    const form = new FormData();
    form.append('audio', fs.createReadStream(audioPath));

    const response = await axios.post('http://localhost:4800/api/transcribe', form, {
        headers: form.getHeaders(),
    });

    console.log(response.data.text);
}

transcribe('recording.wav');

Bash/curl

#!/bin/bash

curl -X POST http://localhost:4800/api/transcribe \
  -F "audio=@recording.wav" \
  | jq '.text'

Important Notes

Security: The API do not allow CORS and only accept request from localhost & 127.0.0.1
Sequential Processing: Transcription requests are processed sequentially due to the single transcription engine (concurrent requests will queue)
Custom Dictionary: Custom dictionary settings are automatically applied to transcriptions
Language Detection: Parakeet automatically detects the language from the audio (no need to specify)
WAV Format Only: Currently only supports WAV files. Other formats must be converted first

Troubleshooting

Port Already in Use

If you get a "Address already in use" error:

Change the port in Settings → System to an unused port (1024-65535)
Or close any other application using that port

"Model not available" Error

Make sure HyperYap runs correctly in the UI and that your model files are not corrupted.
If the issue persists, reinstall the latest version of HyperYap.

No Response from API

Check that the API toggle is ON in Settings → System
Verify the port number matches your request
Ensure HyperYap is still running
Check your firewall isn't blocking localhost access

Slow Transcription

First request will be slower (model warming up)
Subsequent requests should be faster
Very long audio files may take time to process
Check that HyperYap isn't being used for other tasks simultaneously

Limitations

Audio files must be in WAV format - other formats will return an error
Maximum file size: 100 MB
Only 16kHz mono audio is truly optimal (others are resampled automatically)
Real-time streaming is not supported (only pre-recorded files)
No request queueing or status tracking (submit one request at a time)

FilesExpand file tree

API_USAGE.md

Latest commit

History