README

Official PHP client for VoiceKit — the REST API for Russian speech: neural speech synthesis (TTS), transcription (STT) with diarization and timestamps, sentiment analysis, voice cloning, voice biometrics, audio/video effects, call QA, semantic search over recordings and batch operations.

Links: Website · Documentation · API reference · Pricing · Blog

No runtime dependencies: PHP 8.1+ with ext-json. cURL is used when available and the SDK falls back to PHP streams when it is not; streaming sessions use raw sockets, so no WebSocket extension is needed either.

Install

composer require lomshakov/voicekit-client

Quick start

<?php

require 'vendor/autoload.php';

use VoiceKit\VoiceKitClient;

$client = new VoiceKitClient('rtt_…');       // or VoiceKitClient::fromEnvironment()

// Speech synthesis → raw audio bytes
$audio = $client->synthesize('Привет! Это синтез русской речи.', voice: 'preset_anna', format: 'mp3');
file_put_contents('speech.mp3', $audio);

// Transcription (async → poll)
$job = $client->transcribe('speech.mp3', language: 'ru', diarization: true, keyterms: ['диагноз', 'препарат']);

do {
    $result = $client->getTranscriptionJob($job->str('job_id'));
    usleep(1_000_000);
} while (!in_array($result->str('status'), ['completed', 'failed'], true));

echo $result->str('text'), PHP_EOL;

Configuration

$client = new VoiceKitClient(
    apiKey: 'rtt_…',                              // required
    baseUrl: 'https://ttsapi.ru',                 // default
    timeout: 120.0,                               // default, seconds
    transport: new CurlTransport(timeout: 60.0),  // optional
    headers: ['X-Trace' => 'abc'],                // optional, sent with every request
);

VoiceKitClient::fromEnvironment('VOICEKIT_API_KEY') reads the key from the environment, and any VoiceKit\Http\Transport implementation can replace the built-in one (proxy, PSR-18 bridge, test double).

Error handling

Every non-2xx response becomes a VoiceKit\VoiceKitError carrying the RFC 7807 code; network failures carry a message and no status:

use VoiceKit\VoiceKitError;

try {
    foreach ($client->synthesizeStream($longText) as $chunk) {
        // …
    }
} catch (VoiceKitError $error) {
    if ($error->isForbidden()) {
        echo 'upgrade your plan: ', $error->errorCode(); // streaming_forbidden
    } elseif ($error->isCode('quota_exceeded')) {
        echo 'monthly quota is over';
    } elseif ($error->isRateLimited()) {
        echo 'slow down';
    } else {
        echo $error->getMessage();
    }
}

Features

Area	Methods
Synthesis	`synthesize`, `synthesizeStream`, `synthesizeAsync`, `getSynthesisJob`, `downloadSynthesisAudio`
Voices	`voices`, `voice`, `createCloneVoice`, `listCloneVoices`, `getCloneVoice`, `deleteCloneVoice`
Transcription	`transcribe`, `transcribeSync`, `getTranscriptionJob`, `subtitles`, `translateTranscript`, `vad`
Analysis	`analyze`, `analyzeSync`, `getAnalysisJob`, `evaluate`
Text intelligence	`detectLanguage`, `redact`, `topics`, `summarize`, `moderate`
Effects	`applyAudioEffects`, `applyVideoEffects`, `cleanAudio` + job/status/download helpers
Voice ID	`analyzeVoice`, `enrollVoice`, `verifyVoice`, `identifyVoice`, `listVoiceProfiles`, `deleteVoiceProfile`
Recordings	`listRecordings`, `getRecording`, `recordingTranscript`, `recordingSpeakers`, `updateRecording`, `updateSpeaker`, `recordingFromLink`, `exportRecording`, `downloadRecordingAudio`, share links
Call QA	`qaEvaluate`, `qaAnalytics`, `qaEvaluations`, `qaExport`
Search	`search`, `ask`, `meetingProtocol`
Batch / account	`batchSynthesize`, `batchAnalyze`, `getBatch`, `usage`, `billingBalance`
Streaming	`transcribeStream`, `vadStream` (WebSocket, Pro/Business)

Streaming synthesis (Pro/Business)

$out = fopen('long.mp3', 'wb');

foreach ($client->synthesizeStream($longText, voice: 'preset_anna') as $chunk) {
    fwrite($out, $chunk); // chunks arrive as the engine produces them
}

fclose($out);

Audio effects (Free/Basic/Pro/Business)

use VoiceKit\Effects;

$chain = Effects::encode([
    ['type' => 'reverb', 'room_size' => 0.5],
    ['type' => 'pitch', 'semitones' => 2],
]);

// Inline during synthesis
$audio = $client->synthesize('Привет!', voice: 'preset_anna', effects: $chain);

// Or as a background job over an existing file
$job = $client->applyAudioEffects('voice.wav', [
    ['type' => 'compressor', 'ratio' => 3],
], outputFormat: 'mp3');

$processed = $client->downloadAudioEffects($job->str('job_id'));

Audio cleaning (Free/Basic/Pro/Business)

$job = $client->cleanAudio('noisy.wav'); // one click: denoise + normalize

$job = $client->cleanAudio('noisy.wav', [ // or a custom preset
    'denoise' => ['strength' => 0.8, 'stationary' => true],
    'normalize' => ['target_db' => -1.0],
    'high_pass' => 80,
    'low_pass' => 12000,
]);

$clean = $client->downloadAudioCleaning($job->str('job_id'));

Voice ID (Pro/Business)

// Voice passport: language, gender, age, emotion, speaker embedding, AI-vs-human
$passport = $client->analyzeVoice('sample.wav');

// Voice biometrics over your own profiles
$profile = $client->enrollVoice('speaker.wav', 'Алиса');
$check = $client->verifyVoice('other.wav', $profile->str('profile_id'));
$match = $client->identifyVoice('other.wav'); // 1:N over every profile

Recordings, QA & meeting intelligence (Pro/Business)

$page = $client->listRecordings(source: 'link', limit: 10);
$job = $client->recordingFromLink('https://example.com/call.mp3', 'ru');
$speakers = $client->recordingSpeakers($recordingId);
$client->updateSpeaker($recordingId, 'SPEAKER_00', displayName: 'Иван', role: 'operator');

$client->updateRecording($recordingId, tags: ['sales', 'warm'], folder: 'Q3');
$pdf = $client->exportRecording($recordingId, 'pdf');

$evaluation = $client->qaEvaluate($recordingId, [
    ['id' => 'greeting', 'kind' => 'required', 'description' => 'Поздоровался', 'weight' => 1.0],
]);
$trend = $client->qaAnalytics(30);

$hits = $client->search('почему клиент отказался?', limit: 5, keywords: 'дорого');
$answer = $client->ask('почему клиент отказался от Pro?');
$protocol = $client->meetingProtocol($recordingId, 'standup');

WebSocket streaming (Pro/Business)

$stream = $client->transcribeStream(language: 'ru', keyterms: ['диагноз']);

$stream->sendAudio($pcm16Chunk); // raw PCM16, 16 kHz mono
$stream->stop();                 // finalize the utterance

while (($event = $stream->receive()) !== null) {
    // session / vad / partial / final / error
    echo $event->str('type'), ': ', $event->str('text'), PHP_EOL;
}

$stream->close();

Batches

use VoiceKit\File;

$batch = $client->batchSynthesize([
    ['text' => 'Первый текст', 'voice' => 'preset_anna'],
    ['text' => 'Второй текст', 'voice' => 'preset_dmitri'],
]);

$status = $client->getBatch($batch->str('batch_id'));

// Analysis batches take inline base64 audio
$batch = $client->batchAnalyze([
    ['audio' => File::base64Of('call.wav'), 'language' => 'ru'],
]);

Dynamic responses

The API evolves, so JSON answers come back as VoiceKit\Result — an array-backed object with typed accessors. Nested objects are wrapped too, and array access works as usual:

$result = $client->getTranscriptionJob($jobId);

$text = $result->str('text');
$seconds = $result->float('duration_seconds');
$status = $result['status'];

foreach ($result->list('segments') as $segment) {
    echo $segment->float('start'), ' ', $segment->str('text'), PHP_EOL;
}

Result implements ArrayAccess, Countable, IteratorAggregate and JsonSerializable; toArray() returns the untouched payload.

Calling endpoints the SDK does not wrap yet

$response = $client->request('POST', '/v1/synthesize', body: json_encode(['text' => 'Привет']));

$usage = $client->get('/v1/usage');
$voices = $client->getList('/v1/voices');
$tags = $client->getStrings('/v1/recordings/tags');
$audio = $client->download('/v1/recordings/rec_1/audio');
$job = $client->upload('/v1/vad', [['audio', File::fromPath('call.wav')]]);

Requirements

PHP	`ext-json`	`ext-curl`	`ext-openssl`
8.1+	required	recommended (falls back to streams)	required for `wss://` streaming

Development

composer install
composer test        # PHPUnit, offline (live tests are skipped)
composer analyse     # PHPStan level 8
VOICEKIT_API_KEY=rtt_… vendor/bin/phpunit --testsuite integration

lomshakov / voicekit-client

Package info

Security

Statistics