Документация по API для озвучки нейросетями

09 сентября 2025 , Обновлено 19 февраля 2026

Что такое API Звукограма

API Звукограма позволяет программно озвучивать текст нейросетями — без браузера и ручной работы. Вы отправляете текст и параметры голоса через HTTP-запрос и получаете готовый аудиофайл.

Для чего это нужно:

Автоматическая озвучка статей, новостей, уведомлений
Интеграция TTS в ваше приложение, бота, CRM
Пакетная озвучка большого количества текстов
Генерация подкастов, аудиокниг, обучающих материалов

Базовый URL для всех запросов:

https://zvukogram.com/index.php?r=api

Примеры на GitHub | Список всех голосов (JSON) | Рейтинг голосов

Как начать: 1. Пополните баланс — API доступен только после пополнения.
2. Скопируйте token из личного кабинета.
3. Отправьте первый запрос — ниже есть готовые примеры на PHP, Python, cURL и JavaScript.

Какой метод выбрать

В API есть два подхода к озвучке. Выберите тот, который подходит под вашу задачу:

Метод	Как работает	Когда использовать
`/text`	Отправили запрос — сразу получили файл в ответе. 1 шаг.	Короткие тексты до 1000 символов. Быстрый результат без ожидания.
`/longtext`	Отправили запрос — получили `id` задачи. Потом опрашиваете `/result`, пока файл не будет готов. 2 шага.	Длинные тексты до 1 000 000 символов. Книги, статьи, большие объёмы.
`/subs`	Как `/longtext`, но дополнительно возвращает таймкоды (субтитры). 2 шага.	Когда нужна озвучка с привязкой текста ко времени (видео, презентации).

Совет: длинный текст через /text Если вы хотите использовать быстрый метод /text для длинных текстов — разбивайте текст программно по предложениям (до 1000 символов на запрос), озвучивайте каждый фрагмент отдельно и склеивайте аудиофайлы у себя на сервере. Это даёт мгновенный результат без ожидания очереди.

Аутентификация

Каждый запрос к API должен содержать два обязательных параметра:

Параметр	Тип	Описание
`token`	string	Ваш секретный API-ключ. Находится в личном кабинете. Никому не передавайте.
`email`	string	E-mail, на который зарегистрирован аккаунт.

Форматы передачи данных: API принимает данные тремя способами — используйте любой удобный:
1) POST с application/x-www-form-urlencoded (самый распространённый)
2) POST с application/json в теле запроса
3) GET с параметрами в query string

Вариант 1: /text — быстрая озвучка (1 шаг)

POST GET

https://zvukogram.com/index.php?r=api/text

Самый простой способ озвучить текст. Вы отправляете один запрос и сразу получаете готовый аудиофайл в ответе. Не нужно ничего ждать, не нужно делать второй запрос.

Ограничение: максимум 1000 символов в одном запросе. Если текст длиннее — используйте /longtext или разбивайте текст на части (см. совет ниже).

Обязательные параметры

Параметр	Тип	Описание
`token`	string	Ваш API-ключ
`email`	string	E-mail аккаунта
`voice`	string	Имя голоса. Например: `Matthew plus`, `Мартын`. Полный список — api/voices
`text`	string	Текст для озвучки (до 1000 символов)

Необязательные параметры

Все параметры ниже опциональны. Если не указаны — используются значения по умолчанию.

Голос и стиль

Параметр	Тип	По умолч.	Описание
`speed`	float	1	Скорость речи. Диапазон 0.1 … 2.0. Например, `0.8` — медленнее, `1.3` — быстрее.
`pitch`	int	0	Тональность голоса. От −20 (ниже) до 20 (выше).
`style`	string	—	Эмоциональный стиль голоса: `newscast`, `cheerful`, `sad` и др. Доступно не для всех голосов. Смотреть голоса. Ранее этот параметр назывался `emotion` — старое название тоже работает.
`styledegree`	string	—	Интенсивность стиля. Например `1.5` — усиленная эмоция. Работает только совместно с `style`.
`role`	string	—	Роль голоса: `YoungAdultMale`, `OlderAdultFemale` и др. Доступно не для всех голосов.

Паузы и громкость

Параметр	Тип	По умолч.	Описание
`pause_sentence`	int	—	Пауза между предложениями в миллисекундах. Например, `300` — 0.3 секунды.
`pause_paragraph`	int	—	Пауза между абзацами в миллисекундах. Например, `500` — полсекунды.
`volume`	int	100	Громкость результата. `100` — нормально, `150` — громче, `50` — тише. Диапазон 10…200.
`effect`	string	—	Аудиоэффект, например `car` (звук в машине). Доступно для некоторых голосов.

Формат и качество звука

Параметр	Тип	По умолч.	Описание
`format`	string	mp3	Формат выходного файла: `mp3`, `wav`, `ogg`, `opus`, `flac`
`sample_rate`	int	—	Частота дискретизации в Hz. Например: `24000`, `44100`, `48000`. Чем выше — тем лучше качество.
`bitrate`	int	—	Битрейт в kbps для lossy-форматов (mp3, ogg, opus). Диапазон 6…320. Например: `128`, `192`, `320`.
`channels`	int	—	Количество каналов: `1` — моно, `2` — стерео.

Фоновая музыка

К озвучке можно добавить фоновую музыку. Музыка будет звучать под голосом.

Параметр	Тип	Описание
`music`	int	ID фоновой музыки из каталога. Если не указан — озвучка без музыки.
`musik_volume`	int	Громкость музыки. `100` — нормально, `50` — тихо, `150` — громко. Диапазон 5…200.
`musik_loop`	int	Зациклить музыку: `1` — да (музыка повторяется, пока не закончится речь), `0` — нет.

Пример запроса /text

curl -X POST "https://zvukogram.com/index.php?r=api/text" \
  -d "token=ВАШ_ТОКЕН" \
  -d "email=you@example.com" \
  -d "voice=Matthew plus" \
  -d "text=Привет! Это тестовая озвучка через API." \
  -d "format=mp3" \
  -d "speed=1" \
  -d "sample_rate=24000" \
  -d "bitrate=192" \
  -d "channels=2"

<?php
$url = "https://zvukogram.com/index.php?r=api/text";
$data = [
    'token'  => 'ВАШ_ТОКЕН',
    'email'  => 'you@example.com',
    'voice'  => 'Matthew plus',
    'text'   => 'Привет! Это тестовая озвучка через API.',
    'format' => 'mp3',
    'speed'  => 1,
    'sample_rate' => 24000,
    'bitrate'     => 192,
    'channels'    => 2,
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_URL  => $url,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($data),
    CURLOPT_SSL_VERIFYHOST => false,
    CURLOPT_SSL_VERIFYPEER => false,
]);

$response = curl_exec($ch);
if (curl_errno($ch)) die("Ошибка cURL: " . curl_error($ch));
curl_close($ch);

$result = json_decode($response, true);

if ($result['status'] == 1) {
    // Озвучка готова — скачиваем файл
    echo "Файл: " . $result['file'] . "\n";
    echo "Длительность: " . $result['duration'] . " сек\n";
    echo "Стоимость: " . $result['cost'] . " токенов\n";
    copy($result['file'], 'output.' . $result['format']);
} else {
    echo "Ошибка: " . ($result['error'] ?? 'Неизвестная ошибка');
}

import requests

url = "https://zvukogram.com/index.php?r=api/text"
data = {
    "token": "ВАШ_ТОКЕН",
    "email": "you@example.com",
    "voice": "Matthew plus",
    "text": "Привет! Это тестовая озвучка через API.",
    "format": "mp3",
    "speed": 1,
    "sample_rate": 24000,
    "bitrate": 192,
    "channels": 2,
}

response = requests.post(url, data=data, timeout=60)
result = response.json()

if result.get("status") == 1:
    # Озвучка готова — скачиваем файл
    print("Файл:", result["file"])
    print("Длительность:", result["duration"], "сек")
    print("Стоимость:", result["cost"], "токенов")

    # Скачиваем аудио
    audio = requests.get(result["file"])
    with open(f'output.{result["format"]}', "wb") as f:
        f.write(audio.content)
else:
    print("Ошибка:", result.get("error", "Неизвестная ошибка"))

const url = "https://zvukogram.com/index.php?r=api/text";

const data = new URLSearchParams({
    token: "ВАШ_ТОКЕН",
    email: "you@example.com",
    voice: "Matthew plus",
    text: "Привет! Это тестовая озвучка через API.",
    format: "mp3",
    speed: "1",
    sample_rate: "24000",
    bitrate: "192",
    channels: "2",
});

const resp = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: data.toString(),
});

const result = await resp.json();

if (result.status === 1) {
    console.log("Файл:", result.file);
    console.log("Длительность:", result.duration, "сек");
} else {
    console.error("Ошибка:", result.error);
}

Ответ /text (JSON)

В случае успеха (status = 1) ответ содержит ссылку на готовый аудиофайл:

{
  "id": "2870459",
  "status": 1,
  "file": "https://zvukogram.com/texttomp3/20260114/p_2870459_342.mp3",
  "file_cors": "https://zvukogram.com/index.php?r=site/download&prj=2870459&cors=...",
  "parts": "1",
  "parts_done": "1",
  "duration": 3,
  "format": "mp3",
  "error": "",
  "balans": "11563.364",
  "cost": 0.042
}

Поля ответа

Поле	Описание
`id`	Уникальный ID озвучки
`status`	`1` — файл готов, `-1` — ошибка (см. поле `error`)
`file`	Прямая ссылка на аудиофайл — скачивайте или проигрывайте
`file_cors`	CORS-ссылка — используйте, если загружаете файл из браузера (JavaScript)
`duration`	Длительность аудио в секундах
`format`	Формат файла (mp3, wav, flac…)
`balans`	Остаток на вашем балансе (в токенах)
`cost`	Сколько токенов списано за эту озвучку
`error`	Текст ошибки (при `status = -1`)

Совет: пакетная озвучка через /text Если вам нужно озвучить длинный текст, но вы хотите получать результат мгновенно (без очереди /longtext), разбейте текст по предложениям. Каждый фрагмент должен быть до 1000 символов. Озвучивайте фрагменты последовательно через /text и склеивайте аудиофайлы на своей стороне (например, через ffmpeg). Это быстрее, чем ждать обработки через /longtext.

Вариант 2: /longtext — озвучка длинных текстов (2 шага)

POST GET

https://zvukogram.com/index.php?r=api/longtext

Этот метод предназначен для озвучки больших текстов — до 1 000 000 символов (книги, статьи, документы). В отличие от /text, результат приходит не сразу — озвучка ставится в очередь и обрабатывается на сервере.

Как это работает

Алгоритм (2 шага): Шаг 1. Отправляете текст на /longtext — в ответе получаете id задачи и status = 0 (в работе).
Шаг 2. Опрашиваете /result с этим id каждые 2–5 секунд. Когда status станет 1 — файл готов, забираете ссылку из поля file.

Параметры запроса — точно такие же, как у /text (voice, text, format, speed, pitch, style, sample_rate, bitrate, channels, music и т.д.). Единственное отличие — нет ограничения в 1000 символов.

Пример /longtext + /result

# Шаг 1: отправляем текст, получаем id задачи
curl -X POST "https://zvukogram.com/index.php?r=api/longtext" \
  -d "token=ВАШ_ТОКЕН" \
  -d "email=you@example.com" \
  -d "voice=Matthew plus" \
  -d "text=Здесь ваш длинный текст, который может быть на тысячи символов..." \
  -d "format=mp3" \
  -d "sample_rate=24000" \
  -d "bitrate=128" \
  -d "channels=1"

# Ответ: {"id":"4153594","status":0,...}

# Шаг 2: опрашиваем результат (повторяем каждые 2 сек, пока status != 0)
curl -X POST "https://zvukogram.com/index.php?r=api/result" \
  -d "token=ВАШ_ТОКЕН" \
  -d "email=you@example.com" \
  -d "id=4153594"

# Когда status=1, в поле "file" будет ссылка на готовый аудиофайл

<?php
$BASE  = "https://zvukogram.com/index.php?r=api";
$TOKEN = "ВАШ_ТОКЕН";
$EMAIL = "you@example.com";

// Вспомогательная функция для POST-запросов
function postForm($url, $data) {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_URL  => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($data),
        CURLOPT_SSL_VERIFYHOST => false,
        CURLOPT_SSL_VERIFYPEER => false,
    ]);
    $raw = curl_exec($ch);
    if (curl_errno($ch)) die("Ошибка cURL: " . curl_error($ch));
    curl_close($ch);
    return json_decode($raw, true);
}

// ШАГ 1: Отправляем текст на озвучку
$create = postForm($BASE . "/longtext", [
    'token'  => $TOKEN,
    'email'  => $EMAIL,
    'voice'  => 'Matthew plus',
    'text'   => 'Здесь ваш длинный текст...',
    'format' => 'mp3',
    'sample_rate' => 24000,
    'bitrate'     => 128,
    'channels'    => 1,
]);

$id = $create['id'] ?? 0;
if (!$id) die("Ошибка: " . ($create['error'] ?? 'Не получен id'));
echo "Задача создана, id=$id\n";

// ШАГ 2: Опрашиваем результат каждые 2 секунды
for ($i = 0; $i < 600; $i++) {
    $res = postForm($BASE . "/result", [
        'token' => $TOKEN, 'email' => $EMAIL, 'id' => $id
    ]);

    if (($res['status'] ?? 0) == 1) {
        echo "Файл готов: " . $res['file'] . "\n";
        echo "Длительность: " . $res['duration'] . " сек\n";
        copy($res['file'], 'output.' . $res['format']);
        break;
    }

    if (($res['status'] ?? 0) == -1) {
        die("Ошибка: " . ($res['error'] ?? 'Неизвестная'));
    }

    echo "В обработке... ({$res['parts_done']}/{$res['parts']})\n";
    sleep(2);
}

import time
import requests

BASE  = "https://zvukogram.com/index.php?r=api"
TOKEN = "ВАШ_ТОКЕН"
EMAIL = "you@example.com"

# ШАГ 1: Отправляем текст на озвучку
create = requests.post(f"{BASE}/longtext", data={
    "token": TOKEN,
    "email": EMAIL,
    "voice": "Matthew plus",
    "text": "Здесь ваш длинный текст...",
    "format": "mp3",
    "sample_rate": 24000,
    "bitrate": 128,
    "channels": 1,
}, timeout=60).json()

pid = create.get("id")
if not pid:
    raise RuntimeError(f"Ошибка: {create.get('error', 'Не получен id')}")
print(f"Задача создана, id={pid}")

# ШАГ 2: Опрашиваем результат каждые 2 секунды
for _ in range(600):
    res = requests.post(f"{BASE}/result", data={
        "token": TOKEN, "email": EMAIL, "id": pid
    }, timeout=60).json()

    if res.get("status") == 1:
        print(f"Файл готов: {res['file']}")
        print(f"Длительность: {res['duration']} сек")
        audio = requests.get(res["file"])
        with open(f"output.{res['format']}", "wb") as f:
            f.write(audio.content)
        break

    if res.get("status") == -1:
        raise RuntimeError(f"Ошибка: {res.get('error')}")

    print(f"В обработке... ({res.get('parts_done')}/{res.get('parts')})")
    time.sleep(2)

const BASE = "https://zvukogram.com/index.php?r=api";

async function postForm(path, obj) {
    const resp = await fetch(`${BASE}/${path}`, {
        method: "POST",
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
        body: new URLSearchParams(obj).toString(),
    });
    return await resp.json();
}

// ШАГ 1: Отправляем текст на озвучку
const create = await postForm("longtext", {
    token: "ВАШ_ТОКЕН",
    email: "you@example.com",
    voice: "Matthew plus",
    text: "Здесь ваш длинный текст...",
    format: "mp3",
    sample_rate: "24000",
    bitrate: "128",
    channels: "1",
});

if (!create.id) throw new Error(create.error || "Не получен id");
const id = String(create.id);
console.log(`Задача создана, id=${id}`);

// ШАГ 2: Опрашиваем результат каждые 2 секунды
for (let i = 0; i < 600; i++) {
    const res = await postForm("result", {
        token: "ВАШ_ТОКЕН", email: "you@example.com", id
    });

    if (res.status === 1) {
        console.log("Файл готов:", res.file);
        console.log("Длительность:", res.duration, "сек");
        break;
    }

    if (res.status === -1) throw new Error(res.error || "Ошибка");

    console.log(`В обработке... (${res.parts_done}/${res.parts})`);
    await new Promise(r => setTimeout(r, 2000));
}

Ответ шага 1

При создании задачи сервер возвращает status = 0 (задача в очереди) и id для отслеживания:

{
  "id": "4153594",
  "status": 0,
  "parts": "5",
  "parts_done": "0",
  "format": "mp3",
  "error": "",
  "balans": "3331.272",
  "cost": 0.00
}

Ответ шага 2 (когда файл готов)

Когда status станет 1, появятся поля file и duration:

{
  "id": "4153594",
  "status": 1,
  "file": "https://zvukogram.com/texttomp3/.../result.mp3",
  "file_cors": "https://zvukogram.com/index.php?r=site/download&prj=4153594&cors=...",
  "parts": "5",
  "parts_done": "5",
  "duration": 42,
  "format": "mp3",
  "error": "",
  "balans": "3331.272",
  "cost": 1.26
}

Как часто опрашивать /result? Рекомендуем каждые 2 секунды для коротких текстов. Для очень длинных текстов (книги) можно увеличить интервал до 5 секунд, чтобы не нагружать сервер.

/subs — озвучка с субтитрами (2 шага)

POST GET

https://zvukogram.com/index.php?r=api/subs

Работает так же, как /longtext (2 шага: отправить → опросить результат), но дополнительно возвращает таймкоды — привязку фрагментов текста ко времени. Это полезно для создания субтитров к видео, караоке, обучающих материалов.

Дополнительные параметры

Помимо всех параметров из /text, метод /subs принимает:

Параметр	Тип	Описание
`speed_type`	int	Тип управления скоростью: `1` или `2`
`speed_floor`	int	Дополнительный параметр скорости/паузы

Пример запроса — аналогичен /longtext, только URL меняется на /subs и добавляются speed_type/speed_floor. В ответе /result дополнительно появляется поле cuts — массив со ссылками на аудиофрагменты.

/result — получить результат

POST GET

https://zvukogram.com/index.php?r=api/result

Этот эндпоинт используется только после /longtext или /subs. Для /text он не нужен — файл приходит сразу.

Передайте id задачи, полученный на шаге 1, и сервер вернёт текущий статус. Опрашивайте этот эндпоинт в цикле, пока status не станет 1 (готово) или -1 (ошибка).

Параметры

Параметр	Тип	Обяз.	Описание
`token`	string	да	API ключ
`email`	string	да	E-mail аккаунта
`id`	int	да	ID задачи, полученный из `/longtext` или `/subs`

Поля ответа

Поле	Описание
`status`	`0` — ещё обрабатывается (ждите), `1` — готово (забирайте файл), `-1` — ошибка
`file`	Прямая ссылка на аудиофайл (появляется при `status = 1`)
`file_cors`	CORS-ссылка для загрузки из браузера
`cuts`	Массив фрагментов (при использовании `/subs` или тега `obrezka`)
`parts / parts_done`	Всего фрагментов / завершено — удобно для прогресс-бара
`duration`	Длительность в секундах (при `status = 1`)
`balans`	Остаток баланса
`cost`	Итоговая стоимость (растёт по мере обработки фрагментов)

Вспомогательные эндпоинты

/voices — список голосов

GET

https://zvukogram.com/index.php?r=api/voices

Возвращает JSON-массив со всеми доступными голосами. Используйте для построения интерфейса выбора голоса в вашем приложении.

Можно отфильтровать по языкам:

https://zvukogram.com/index.php?r=api/voices&langs=en,ru

/balance — проверка баланса

POST GET

https://zvukogram.com/index.php?r=api/balance

Параметры: token, email. Возвращает текущий остаток баланса в токенах.

/delete — удалить проект

POST GET

https://zvukogram.com/index.php?r=api/delete

Параметры: token, email, id. Удаляет проект и аудиофайл с сервера.

Форматы, sample_rate и bitrate

API поддерживает несколько аудиоформатов:

Формат	Тип	Когда использовать
`mp3`	lossy	Универсальный формат. Подходит для большинства задач.
`ogg`	lossy	Хорошее качество при малом размере. Популярен в вебе.
`opus`	lossy	Лучшее качество при низких битрейтах. Идеален для стриминга.
`wav`	lossless	Без сжатия. Максимальное качество, но большой размер.
`flac`	lossless	Сжатие без потерь. Качество как у WAV, но файл компактнее.

Чем отличаются sample_rate и bitrate

Параметр	Что это	Единицы	Примеры
`sample_rate`	Частота дискретизации — сколько раз в секунду записывается звук. Чем выше — тем детальнее.	Hz	`24000`, `44100`, `48000`
`bitrate`	Битрейт — сколько данных на секунду аудио. Актуально только для lossy (mp3, ogg, opus).	kbps	`64`, `128`, `192`, `320`

Обратная совместимость bitrate / sample_rate Ранее параметр bitrate в API фактически управлял частотой дискретизации (Hz), а не битрейтом. Сейчас это исправлено: bitrate — настоящий битрейт (kbps), а для частоты добавлен sample_rate.

Для совместимости: если sample_rate не указан и bitrate содержит значение, похожее на Hz (например 48000), сервер автоматически интерпретирует его как sample_rate. Старый код продолжит работать.

FLAC / WAV: У lossless-форматов битрейт не фиксированный. Если Windows показывает 300–1200+ kbps для FLAC — это нормально, так работает сжатие без потерь.

Ошибки и статусы

Все ответы API содержат поле status:

status	Значение	Что делать
`1`	Готово	Файл готов — забирайте из поля `file`
`0`	В обработке	Повторите `/result` через 2 секунды
`-1`	Ошибка	Причина — в поле `error`

Частые ошибки:

Пустой или неверный token — проверьте ключ в личном кабинете
Текст длиннее 1000 символов для /text — используйте /longtext или разбивайте текст
Неизвестное имя голоса — проверьте через /voices
Недостаточно токенов — пополните баланс

Инструкции

Профиль

SSML

Разработчикам

Документация по API для озвучки нейросетями

Что такое API Звукограма

Какой метод выбрать

Аутентификация

Вариант 1: /text — быстрая озвучка (1 шаг)

Обязательные параметры

Необязательные параметры

Голос и стиль

Паузы и громкость

Формат и качество звука

Фоновая музыка

Пример запроса /text

Ответ /text (JSON)

Поля ответа

Вариант 2: /longtext — озвучка длинных текстов (2 шага)

Как это работает

Пример /longtext + /result

Ответ шага 1

Ответ шага 2 (когда файл готов)

/subs — озвучка с субтитрами (2 шага)

Дополнительные параметры

/result — получить результат

Параметры

Поля ответа

Вспомогательные эндпоинты

/voices — список голосов

/balance — проверка баланса

/delete — удалить проект

Форматы, sample_rate и bitrate

Чем отличаются sample_rate и bitrate

Ошибки и статусы

Поддержка

Содержание