API синтеза речи: документация, примеры кода и цены

Автор Редакция ГолосНПЦ · Обновлено 2026-11-19

Здесь вы найдете полную документацию по API синтеза речи ГолосНПЦ: примеры запросов, описание параметров и готовые сниппеты кода. Мы показали, как интегрировать озвучку NPC в ваши игровые проекты, используя знакомые инструменты вроде OpenAI SDK или простой curl.

Страница поможет новичкам и фрилансерам разобраться в ключах, лимитах и форматах аудио. Вы узнаете, как отправлять текст, настраивать скорость и получать готовые MP3-файлы. Все примеры основаны на реальных фактах сервиса: от лимита в 60 запросов в минуту до стоимости в $0.01 за 1000 символов.

API синтеза речи: документация, примеры кода и цены

Часто задаваемые вопросы

Какой формат ключа API?

Ключ начинается с префикса tts-. Он передается в заголовке Authorization: Bearer tts-... У каждого аккаунта только один активный ключ. При выпуске нового старый мгновенно становится недействительным. Ключ можно обновить в любое время через личный кабинет на странице /get-api-key/.

Можно ли использовать Python SDK?

Официального SDK от нас нет, но вы можете использовать OpenAI SDK для Python. Просто измените параметр base_url на https://api.dbkk.info/v1 и укажите свой API-ключ. Это позволяет использовать знакомые методы библиотеки для отправки запросов на синтез речи без лишних зависимостей.

Как указать голос в запросе?

Укажите имя голоса в поле voice JSON-тела запроса. Доступны восемь пресетов: aria, nova, luna, sage, felix, milo, atlas, orion. Если язык не задан явно, он определяется по скрипту. Для латиницы по умолчанию используется английский, поэтому для других языков латиницы укажите поле language.

Какие параметры скорости доступны?

Параметр speed принимает значения от 0.25 до 4.0. Это позволяет замедлить или ускорить речь в запросе. Значение передается в JSON-теле POST-запроса. Стандартная скорость генерации составляет около 25 символов текста в секунду, что соответствует реальному времени воспроизведения для длинных текстов.

Возвращается ли аудио в ответе?

Да, сгенерированный аудиофайл возвращается непосредственно в ответе на запрос. Данные не сохраняются на наших серверах. Исходный текст используется только для создания аудио и не передается на обучение моделей. Метаданные запроса сохраняются исключительно для целей биллинга и учета использованных символов.

Нужно ли устанавливать дополнительные библиотеки?

Специальные библиотеки не требуются. Вы можете использовать стандартные HTTP-клиенты или OpenAI SDK. Для Python достаточно установить openai. Для других языков подойдет любой инструмент для отправки POST-запросов с JSON-телом. Укажите правильный base_url и заголовок авторизации для работы с нашим API.

Как обработать длинный текст?

Максимальный размер текста — 4096 символов на один запрос. Для длинных текстов разделите их на части этого размера. Отправьте каждый фрагмент отдельно и объедините полученные аудиофайлы. Это стандартный подход для работы с API, гарантирующий успешную генерацию всех частей диалога.

Что делать, если запрос завис?

Запросы обрабатываются последовательно, поэтому при высокой нагрузке они могут стоять в очереди. Если синтез не завершился, проверьте статус. Неудачные запросы бесплатны, и сумма возвращается на баланс. Вы можете выпустить новый ключ, если старый перестал работать, или просто повторить запрос.

Есть ли пример запроса на JS?

Да, используйте fetch или axios. Отправьте POST-запрос на https://api.dbkk.info/v1/audio/speech. В заголовке укажите Authorization: Bearer ваш_ключ. В теле запроса укажите model, input, voice и response_format. Примеры кода легко адаптировать из документации OpenAI, изменив базовый URL.

Поддерживается ли асинхронная работа?

API обрабатывает запросы последовательно, поэтому при высокой нагрузке возможны задержки в очереди. API не поддерживает WebSocket или потоковую передачу аудио. Для асинхронной обработки на стороне клиента используйте многопоточность или асинхронные запросы, но учитывайте лимиты и порядок обработки сервером.

Как проверить валидность ключа?

Отправьте любой валидный запрос на синтез речи. Если ключ действителен, вы получите аудиофайл. Если ключ недействителен, сервер вернет ошибку авторизации. Также проверьте баланс и статус ключа в личном кабинете на странице /get-api-key/ после входа в аккаунт.

Какой размер аудиофайла?

Размер зависит от формата, голоса и длительности. Вы можете выбрать mp3, wav, opus, flac или pcm. MP3 обеспечивает компактный размер файла, FLAC — высокое качество без потерь. Скорость генерации составляет около 25 символов в секунду, что влияет на длительность и объем данных.

Можно ли передать текст в base64?

Нет, текст передается в поле input как обычная строка в JSON-теле запроса. Максимальная длина — 4096 символов. Base64 не требуется. Поле input содержит исходный текст для озвучки. Специальные символы и пробелы учитываются при подсчете символов для биллинга.

Где найти список доступных голосов?

Отправьте GET-запрос на endpoint /v1/voices. Этот адрес возвращает список всех доступных голосов, языков, форматов и цен. Базовый URL API: https://api.dbkk.info/v1. Ответ содержит метаданные, необходимые для корректного формирования запросов на синтез речи в ваших приложениях.

Первый запрос

curl

curl https://api.dbkk.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.dbkk.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.dbkk.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariaженский
novaженский
lunaженский
sageженский
felixмужской
miloмужской
atlasмужской
orionмужской
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Получение API ключа

Иллюзация звуковой волны для: Получение API ключа

Для начала работы с API синтеза речи вам потребуется аккаунт на сайте dbkk.info. Регистрация доступна через Google или по электронной почте с паролем. Обратите внимание: пробный баланс в $0,50 (около 50 000 символов) предоставляется только при входе через Google и действует 7 дней. Аккаунты, созданные по email, начинают работу без пробных средств.

Регистрация аккаунта

Регистрация аккаунта

Перейдите на страницу /get-api-key/ и выберите удобный способ входа. После авторизации вы получаете уникальный ключ доступа к эндпоинту https://api.dbkk.info/v1.

  • Вход через Google (с пробным балансом)
  • Вход по Email + пароль (без пробного баланса)

Где найти ключ API

Где найти ключ API

Ваш персональный ключ отображается в личном кабинете сразу после регистрации. Он начинается с префикса tts-. Этот ключ используется в заголовке Authorization: Bearer <ваш_ключ> для всех запросов к API.

Смена ключа безопасности

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

Первый запрос через curl

Иллюзация звуковой волны для: Первый запрос через curl

API синтеза речи ГолосНПЦ принимает запросы в формате JSON и возвращает аудиофайл напрямую в ответе. Это позволяет быстро интегрировать озвучку NPC в игровые движки без лишних промежуточных сервисов. Мы используем стандартный формат, совместимый с популярными SDK, что упрощает отладку.

Для начала работы достаточно выполнить один curl-запрос с вашим API-ключом. Система вернет бинарные данные аудиофайла, который можно сразу сохранить на диск или передать в игровой клиент. Ниже приведены точные параметры и примеры для быстрой интеграции в ваши проекты.

Пример curl команды

Самый простой способ протестировать API — использовать утилиту curl в терминале. Вам нужно указать базовый URL, передать заголовок авторизации с вашим ключом и тело запроса с текстом. Результат будет записан в файл speech.mp3.

Пример команды для генерации речи голосом 'nova': curl -X POST https://api.dbkk.info/v1/audio/speech \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"model": "tts-1", "input": "Привет, путник! Добро пожаловать в таверну.", "voice": "nova", "response_format": "mp3"}' \ -o speech.mp3

Убедитесь, что заменили YOUR_API_KEY на ваш реальный ключ из личного кабинета. Если ключ недействителен, вы получите ошибку 401. Скорость генерации короткой фразы составляет несколько секунд, так как запросы обрабатываются в очереди.

  • Используйте флаг -o для сохранения файла напрямую.
  • Проверяйте код возврата curl: 0 означает успех.
  • Для отладки добавьте флаг -v для вывода заголовков.

Формат JSON запроса

Тело запроса отправляется в формате JSON. Обязательные поля: model (выберите между tts-1 или tts-1-hd), input (текст до 4096 символов) и voice (один из 8 доступных голосов). Поле response_format определяет выходной формат аудио.

Дополнительно можно указать speed (от 0.25 до 4.0) для изменения темпа речи и language (ISO код) для точного определения языка, если он не определен автоматически. Все поля, кроме указанных, игнорируются. Убедитесь, что текст соответствует ожидаемому языку, иначе интонация может быть некорректной.

  • model: "tts-1" или "tts-1-hd".
  • input: строка текста (макс. 4096 символов).
  • voice: имя голоса (например, "nova").
  • response_format: "mp3", "wav", "opus", "flac" или "pcm".

Получение аудиофайла

В случае успешного выполнения сервер возвращает HTTP-код 200 с бинарными данными аудиофайла в теле ответа. Контент-тип заголовка будет соответствовать выбранному формату (например, audio/mpeg для MP3). Эти данные можно напрямую записать на диск или передать в буфер памяти вашего приложения.

Если синтез не удался, вы получите JSON с описанием ошибки. Средства за неудачные запросы возвращаются в полном объеме. Для длинных текстов (более 4096 символов) вам нужно самостоятельно разбить текст на части, отправить несколько запросов и склеить полученные аудиофайлы.

Интеграция с OpenAI SDK

Иллюзация звуковой волны для: Интеграция с OpenAI SDK

Ваш API полностью совместим с официальными SDK OpenAI. Это позволяет использовать знакомые методы и структуры кода,仅需 изменив базовый URL на https://api.dbkk.info/v1.

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

Изменение base_url

Укажите базовый URL вашего API в настройках клиента SDK. Это основное изменение, необходимое для перенаправления запросов на наши серверы.

  • Используйте base_url=https://api.dbkk.info/v1

Использование стандартных методов

Применяйте метод audio.speech, ожидающий JSON-тело с полями model, input, voice и response_format. Параметры работают так же, как в OpenAI.

Пример кода на Python

```python import openai client = openai.OpenAI( base_url="https://api.dbkk.info/v1", api_key="tts-ваш_ключ" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Привет! Я озвучка для NPC.", response_format="mp3" ) response.write_to_file("output.mp3") ```

Поддерживаемые форматы аудио

Иллюзация звуковой волны для: Поддерживаемые форматы аудио

API поддерживает пять форматов аудио, позволяя выбрать оптимальное решение для вашего игрового движка или платформы. Вы можете использовать MP3 для компактности, WAV для высокого качества или OPUS, FLAC и PCM в зависимости от требований к размеру файла и совместимости.

Формат MP3

Популярный выбор для игр благодаря сжатому размеру файла и широкой поддержке плееров. Идеально подходит для фоновой речи и коротких реплик NPC, где важна экономия трафика и места на диске.

  • Сжатый формат для экономии места
  • Универсальная совместимость с игровыми движками

Формат WAV

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

  • Высокое качество без потерь
  • Подходит для постобработки

Форматы OPUS, FLAC, PCM

OPUS обеспечивает отличное соотношение качества и размера, FLAC — сжатие без потерь, PCM — сырые данные для максимальной гибкости. Выберите тот, который лучше интегрируется с вашим стеком технологий.

Все форматы возвращаются как бинарные данные в теле ответа API. Просто сохраните их в файл с соответствующим расширением.

  • OPUS: эффективное сжатие
  • FLAC: без потерь качества
  • PCM: сырой аудиопоток

Параметры запроса

Иллюзация звуковой волны для: Параметры запроса

Параметры запроса позволяют гибко настраивать синтез речи под конкретные задачи. Вы можете выбрать модель, задать скорость озвучки и явно указать язык, если текст написан латиницей, но должен звучать не по-английски.

Модели tts-1 и tts-1-hd

В API доступны две модели: tts-1 и tts-1-hd. Обе используют один и тот же движок синтеза, поэтому качество голоса идентично. Разница лишь в коде модели, но цена за символ одинакова для обеих.

Настройка скорости речи

Параметр speed позволяет ускорить или замедлить речь в диапазоне от 0.25 до 4.0. Стандартная скорость равна 1.0. Это удобно для создания динамичных реплик NPC или, наоборот, для медленного повествования в документальных сценах.

Указание языка

Если вы передаете текст на латинице (например, на немецком или испанском), система по умолчанию может принять его за английский. Чтобы избежать ошибок, всегда явно указывайте код языка в параметре language. Это гарантирует корректное произношение.

  • Поддерживаются 23 языка, включая русский, английский, японский и арабский.
Параметры запроса

Лимиты и ограничения

Иллюзация звуковой волны для: Лимиты и ограничения

Мы ценим ваше время и ресурсы, поэтому лимиты настроены так, чтобы балансировать между производительностью и стабильностью. Понимание ограничений поможет вам эффективно планировать генерацию диалогов для NPC без неожиданных задержек.

60 запросов в минуту

Каждый API-ключ ограничен 60 запросами в минуту. Этого достаточно для большинства проектов, но если вы генерируете длинные сценарии, лучше разбивать их на части. До первого пополнения лимит ниже — 10 запросов в минуту.

Лимит символов в одном запросе

Максимальный объем текста для одной генерации — 4096 символов. Если диалог длиннее, разбейте его на фрагменты и объедините аудиофайлы на стороне клиента. Это гарантирует стабильный результат и позволяет контролировать объем данных.

Ограничения скорости генерации

Аудио генерируется последовательно, поэтому при высокой нагрузке запросы могут стоять в очереди. Типичная скорость составляет около 25 символов текста в секунду аудио. Короткие фразы занимают несколько секунд, а длинные сцены обрабатываются в реальном времени.

Обработка ошибок

Иллюзация звуковой волны для: Обработка ошибок

API ГолосНПЦ возвращает стандартные HTTP-коды для диагностики. Используйте их, чтобы быстро найти причину проблемы и исправить запрос, не теряя времени на отладку.

Коды ошибок API

Сервер отвечает кодом 400 при неверном формате JSON или отсутствии обязательных полей. Код 401 означает, что API-ключ недействителен. Ошибка 429 появляется, когда вы превысили лимит в 60 запросов в минуту.

  • 400: Неверный запрос
  • 401: Неавторизован
  • 429: Превышен лимит

Что делать при сбое

При ошибке 400 проверьте синтаксис тела запроса. Если получили 429, сделайте паузу перед повторной отправкой или разделите длинный текст на части до 4096 символов, чтобы снизить нагрузку на очередь.

Возврат средств за ошибки

Если синтез завершился неудачно, средства за этот запрос возвращаются в полном объеме. Баланс не списывается, и вы можете сразу попробовать сгенерировать аудио заново без дополнительных затрат.

Структура ответа API

Иллюзация звуковой волны для: Структура ответа API

API возвращает бинарные данные аудиофайла напрямую в теле ответа. Это упрощает интеграцию: вам не нужно парсить сложные JSON-структуры для получения звука, достаточно сохранить полученный поток в файл.

Успешный запрос возвращает HTTP-статус 200. Если синтез не удался, сервер вернет код 4xx или 5xx с описанием ошибки в теле ответа, что позволяет легко отладить интеграцию.

Формат ответа ['Тело ответа содержит бинарные данные аудиофайла в запрошенном формате (mp3, wav, opus, flac или pcm).', 'Для коротких фраз задержка минимальна, но при больших объемах текста время ответа зависит от длины генерации.'] []

Заголовки ответа ['HTTP-заголовки включают стандартные поля, такие как Content-Type, указывающий на тип аудиофайла.', 'В ответах также передаются метаданные, необходимые для корректной обработки клиентом.']

Данные о биллинге ['В заголовках ответа передаются метрики использования: количество обработанных символов и статус транзакции.', 'Эти данные помогают отслеживать расход средств и контролировать лимиты, так как списание происходит только за успешные синтезы.', 'Неудачные запросы не списывают средства, что отражается в метриках как нулевая стоимость.']

Послушайте 8 голосов

Каждый образец ниже сгенерирован этим API из одного и того же предложения. Она хорошо подходит для обучающих миссий или спокойных торговцев, которые объясняют механику игры.

Аватар голоса aria
ariaженский
Аватар голоса nova
novaженский
Аватар голоса luna
lunaженский
Аватар голоса sage
sageженский
Аватар голоса felix
felixмужской
Аватар голоса milo
miloмужской
Аватар голоса atlas
atlasмужской
Аватар голоса orion
orionмужской

23 языка

Любой голос может говорить на любом из этих языков.

Источники и дополнительные материалы

  1. Wikipedia
  2. Python documentation
  3. IETF RFC 7845: Ogg Opus
  4. MDN: Web Speech API
  5. LibriTTS-R corpus (OpenSLR 141)
  6. TRON developer hub: TRC-20
  7. W3C WAI: making audio and video accessible
  8. Tether (USDT)
  9. Creative Commons Attribution 4.0
  10. Node.js documentation
  11. curl documentation
  12. OpenAI API reference: create speech

Больше на этом сайте