responsivevoice/sdk

PHP client for the ResponsiveVoice Text-to-Speech API.

Documentation | REST API

---

Compatible with the ResponsiveVoice API v2 (OpenAPI spec 2.0.2).

Installation

composer require responsivevoice/sdk

Get your API credentials

You need both an API key and an API secret to authenticate your requests — neither works alone.

1. Register for a free ResponsiveVoice account.
2. A default website is created for you automatically. Its identifier is your API key — copy it from the dashboard.
3. Create your API secret in the dashboard section "Server-to-server API secrets" (it is not auto-generated).
4. The secret is shown once — copy it immediately and store it safely. It can't be retrieved later; if you lose it, create a new one.

PHP runs server-side, which is exactly where the secret belongs — keep it out of any client-side code.

Usage

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use ResponsiveVoice\Sdk\Api\SynthesisApi;
use ResponsiveVoice\Sdk\Configuration;
use ResponsiveVoice\Sdk\Model\SynthesizeRequest;

// Authenticate with BOTH your API key and API secret (see above).
$config = Configuration::getDefaultConfiguration()
    ->setApiKey('X-API-Key', getenv('RESPONSIVEVOICE_API_KEY'))
    ->setApiKey('X-API-Secret', getenv('RESPONSIVEVOICE_API_SECRET'));

$synthesis = new SynthesisApi(new Client(), $config);

// Synthesize speech: pass text and a ResponsiveVoice voice name.
// The server resolves the right voice for you.
$audio = $synthesis->v2TextSynthesizePost(
    (new SynthesizeRequest())
        ->setText('Hello, world!')
        ->setVoice('UK English Female')
        ->setFormat('mp3')
);

// $audio is the raw audio (MP3 bytes) — write it to a file or stream it out.
file_put_contents('hello.mp3', $audio);

Listing voices

use ResponsiveVoice\Sdk\Api\VoicesApi;

$voices = new VoicesApi(new Client(), $config);

// All voices
$all = $voices->v2VoicesGet();
echo count($all->getVoices()) . " voices\n";

// Voices for one language (BCP-47)
$british = $voices->v2VoicesByLanguageLangGet('en-GB');

// A specific voice by name
$voice = $voices->v2VoicesNameGet('UK English Female');
echo $voice->getName() . ' — ' . $voice->getLang() . "\n";

Error handling

API calls throw ResponsiveVoice\Sdk\ApiException on any non-2xx response. Inspect the status code and response body to handle failures.

use ResponsiveVoice\Sdk\ApiException;

try {
    $audio = $synthesis->v2TextSynthesizePost(
        (new SynthesizeRequest())->setText('Hello')->setVoice('UK English Female')
    );
} catch (ApiException $e) {
    // 401/403 — bad or missing credentials; 400 — invalid request; 429 — rate limited.
    fwrite(STDERR, 'Request failed (' . $e->getCode() . '): ' . $e->getResponseBody() . "\n");
}

Examples

Runnable projects live in examples/.

Basic

examples/basic/ — framework-free PHP: two scripts that list voices and synthesize text to an MP3 file.

Laravel

examples/laravel/ — a Laravel app wiring the SDK into the service container (config, service provider, an artisan rv:speak command). It also covers two Laravel gotchas: build a fresh Configuration instead of mutating the static singleton (avoids cross-request credential leakage under Octane), and mock the SDK's own Guzzle client in tests, since Http::fake() won't intercept it.

Support

Questions, bugs, feature requests: support@responsivevoice.org

License

MIT. See LICENSE.

---

Other language SDKs: TypeScript · Python · Go · Java

AI coding agents: install the ResponsiveVoice skill — npx skills add responsivevoice/skills