Часто задаваемые вопросы
Какие SDK поддерживаются?
Официального собственного SDK нет. Вы можете использовать официальные SDK OpenAI, изменив base_url на https://api.ak33.info/v1 и передав свой API-ключ. Также подойдет любой HTTP-клиент для отправки POST-запросов. Это обеспечивает простую интеграцию без необходимости устанавливать дополнительные библиотеки или зависимости.
Можно ли использовать SSML?
Нет, SSML не поддерживается. API принимает только обычный текст в поле input. Вы не можете использовать теги для управления интонацией, паузами или произношением. Если вам нужны точные паузы или акценты, их лучше обрабатывать на стороне клиента или через логику приложения.
Как изменить язык голоса?
Укажите параметр language с кодом ISO в запросе. Если поле опущено, язык определяется автоматически по скрипту текста (латиница по умолчанию — английский). Для точного результата при использовании латиницы для других языков (например, немецкого или польского) обязательно передайте код языка явно.
Какой максимальный размер текста?
Максимальный размер текста составляет 4096 символов на один запрос. Если ваш текст длиннее, его необходимо разбить на части по 4096 символов, сгенерировать аудио для каждой части отдельно, а затем объединить полученные файлы в один непрерывный аудиопоток на стороне вашего приложения.
Поддерживается ли потоковая передача?
Нет, потоковая передача (streaming) не поддерживается. API возвращает готовый аудиофайл в ответе. Также нет WebSocket или частичного аудио. Вы получаете полный файл формата mp3, wav, opus, flac или pcm после завершения синтеза, что подходит для большинства сценариев чат-ботов.
Как определить язык текста?
Если параметр language не указан, система пытается определить язык по скрипту текста. Текст на латинице по умолчанию интерпретируется как английский. Для других языков, использующих латиницу (например, французский или испанский), рекомендуется явно указывать параметр language, чтобы избежать ошибок распознавания.
Можно ли генерировать аудио параллельно?
Запросы обрабатываются последовательно, поэтому под нагрузкой запросы могут стоять в очереди. Это может увеличить время ответа для коротких фраз. Для длинных текстов скорость генерации примерно соответствует реальному времени воспроизведения. Параллельная обработка не гарантируется, что важно учитывать при проектировании интерфейса.
Есть ли ограничения по скорости?
Да, параметр speed регулируется в диапазоне от 0.25 до 4.0. Вы можете ускорять или замедлять речь в зависимости от потребностей вашего голосового ассистента. Это позволяет адаптировать темп речи под контекст, сохраняя естественность звучания выбранного голоса без дополнительных настроек.
Как работает кэширование запросов?
API не использует кэширование запросов. Каждый запрос обрабатывается независимо, и результат не сохраняется для повторного использования. Если вы отправите идентичный текст, он будет синтезирован заново, что потребует повторного списания средств.
Нужно ли указывать модель?
Да, поле model является обязательным. Вы можете выбрать между «tts-1» или «tts-1-hd». Обе модели используют один и тот же движок и стоят одинаково. Разница заключается только в названии модели, так как движок и цена одинаковы.
Какой формат лучше для мобильных приложений?
Для мобильных приложений рекомендуется использовать формат mp3 или opus благодаря их компактному размеру. Opus обеспечивает хорошее качество при малом битрейте, что экономит трафик. Вы также можете выбрать wav или flac, если приоритетом является максимальное качество, а не объем данных.
Можно ли получить сырой PCM?
Да, вы можете получить сырой PCM-аудиофайл, указав response_format: pcm. Это полезно, если вы хотите самостоятельно обрабатывать аудио или передавать его в другие системы. Формат pcm возвращает необработанные аудиоданные без сжатия, что увеличивает размер файла по сравнению с mp3 или opus.
Как обрабатывать длинные тексты?
Разбейте текст на части до 4096 символов. Отправьте каждую часть отдельным запросом к API. Получите аудиофайлы для каждой части и объедините их в один файл на стороне вашего приложения. Это стандартный подход для обработки контента, превышающего лимит одного запроса.
Возвращает ли API метаданные о голосе?
API возвращает сгенерированный аудиофайл в ответе. Метаданные о голосе, такие как список доступных голосов, языков и форматов, доступны через отдельный GET-запрос к эндпоинту /v1/voices. В самом ответе с аудио метаданные голоса не передаются, только сам файл.
Первый запрос
curl
curl https://api.ak33.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.ak33.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.ak33.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 | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Получение ключа доступа
Для работы с API Echolink необходимо создать аккаунт на странице /get-api-key/. Доступны два способа авторизации: через Google-аккаунт или по почте и паролю. Учетные записи создаются для конкретного сайта.
Регистрация аккаунта
Зарегистрироваться можно по email или через Google. При входе через Google сразу начисляется пробный баланс $0.50 (около 50 000 символов), действительный 7 дней. При регистрации по email пробный баланс не начисляется.
Важный ключ
На странице личного кабинета отображается активный ключ формата tts-.... Он используется в заголовке Authorization: Bearer. У аккаунта может быть только один активный ключ одновременно.
Смена ключа
Вы можете выпустить новый ключ в любой момент. Старый ключ перестает действовать мгновенно после генерации нового. Это полезно при ротации учетных данных или если ключ был скомпрометирован.
Первый запрос через curl
Для синтеза речи отправьте POST-запрос на https://api.ak33.info/v1/audio/speech. Тело запроса содержит текст до 4096 символов, имя голоса и формат вывода. API принимает стандартные поля модели, input и voice.
Аутентификация выполняется через заголовок Authorization с вашим ключом API. Один активный ключ позволяет делать до 60 запросов в минуту. Убедитесь, что ключ начинается с префикса tts-.
Тело запроса
JSON-объект должен содержать поля model, input и voice. Поле input принимает строку текста. Максимальная длина — 4096 символов. Для длинных текстов разделите их на части.
Заголовки авторизации
Добавьте заголовок Authorization: Bearer <ваш_ключ>. Ключ выдается при регистрации. При смене ключа старый становится недействительным мгновенно.
Пример команды
Используйте curl для отправки запроса. Укажите параметры в теле запроса. API вернет аудиофайл в указанном формате.
- curl -X POST https://api.ak33.info/v1/audio/speech \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Привет", "voice": "nova", "response_format": "mp3"}'
Интеграция через OpenAI SDK
Поскольку структура запроса API Echolink идентична OpenAI, вы можете использовать официальный OpenAI SDK, изменив базовый URL. Это позволяет интегрировать синтез речи в существующие проекты голосовых ассистентов без написания кастомного HTTP-клиента.
Для Python достаточно указать новый endpoint в конфигурации клиента. Все методы работы с аудио остаются прежними, что упрощает поддержку кодовой базы и снижает порог входа для команд.
Настройка base_url
Укажите базовый URL вашей аккаунтной зоны. Это единственное изменение, необходимое для перенаправления запросов на серверы Echolink вместо OpenAI.
- base_url=https://api.ak33.info/v1
Библиотека Python
Используйте стандартную библиотеку openai. Убедитесь, что версия пакета актуальна для поддержки параметра base_url.
Пример кода
Код ниже демонстрирует инициализацию клиента и отправку запроса на синтез голоса для текстового ввода.
Форматы аудио
API возвращает аудиофайл в выбранном формате, определяя баланс между размером и совместимостью. Поддерживаются MP3, WAV, OPUS и FLAC, что позволяет адаптировать вывод под конкретные требования инфраструктуры голосовых ассистентов.
Выбор формата зависит от задачи: MP3 идеален для веб-воспроизведения, WAV обеспечивает исходное качество, а OPUS и FLAC оптимизированы для эффективной передачи данных и сжатия без потери качества.
MP3 для веба
Формат MP3 обеспечивает максимальную совместимость с браузерами и большинством плееров. Он оптимально сжимает данные, сокращая трафик при воспроизведении синтезированной речи в веб-интерфейсах.
Используйте mp3 в поле response_format, если ваша интеграция воспроизводит аудио через стандартные HTML5-элементы или мобильные приложения с ограниченным каналом связи.
WAV для качества
WAV предоставляет несжатый аудиофайл, сохраняя исходные параметры синтеза. Этот формат подходит для локальной обработки или если вам необходимо избежать любых артефактов сжатия перед дальнейшим анализом звука.
Выбирайте wav, когда важна точность воспроизведения, а объём данных не является критическим ограничением для вашего бэкенда.
OPUS и FLAC
Формат OPUS оптимизирован для эффективной передачи данных и хорошо сжимает аудио без заметной потери качества. FLAC обеспечивает Lossless-сжатие, сохраняя оригинальное качество звука.
Используйте OPUS для экономии трафика при передаче голосовых сообщений в чат-ботах, а FLAC — для архивации или высокоточных задач, где важен полный спектр частот без сжатия.
Параметры запроса
Выбор модели определяет качество и стоимость синтеза, но не меняет движок рендеринга. Поля model и voice являются обязательными в теле запроса для корректной генерации аудиофайла.
Модели синтеза
Доступны два варианта: tts-1 и tts-1-hd. Они используют один и тот же движок синтеза, поэтому качество звука идентично. Цена за миллион символов одинакова для обеих моделей.
- Выбирайте модель по необходимости, так как технически они эквивалентны.
Выбор голоса
В API доступно 8 голосов: Aria, Nova, Luna, Sage (женские) и Felix, Milo, Atlas, Orion (мужские). Каждый голос поддерживает все 23 языка. Если параметр language не задан, система пытается определить язык автоматически.
- 8 голосов на выбор.
- Поддержка 23 языков.
Скорость речи
Параметр speed регулирует темп произношения в диапазоне от 0.25 до 4.0. Значение 1.0 соответствует нормальной скорости. Изменение скорости не влияет на стоимость генерации.

Обработка ошибок
При работе с API важно правильно обрабатывать различные статусы ответов. Это позволяет избежать потери данных и обеспечить стабильную работу голосовых ассистентов.
Статус 400
Ошибка возникает, если текст превышает 4096 символов или указан неизвестный голос. Проверьте формат JSON и соответствие параметров документации.
Статус 429
Лимит составляет 60 запросов в минуту (10 до первого пополнения). При превышении запросы ставятся в очередь или отклоняются. Пополнение баланса не увеличивает лимит, а лишь позволяет продолжать использование.
Статус 500
Внутренняя ошибка сервера. Повторите запрос через несколько секунд. Если ошибка сохраняется, отправьте детали на поддержку по электронной почте.
Лимиты и ограничения
API Echolink спроектирован для стабильной работы в сценариях голосовых ассистентов и чат-ботов. Понимание лимитов и ограничений помогает избежать задержек при интеграции и корректно обрабатывать сценарии высокой нагрузки.
60 запросов в минуту
На один API-ключ действует лимит в 60 запросов в минуту. Этого достаточно для большинства сценариев использования, но при превышении лимита сервер вернет ошибку 429.
- Лимит считается на уровне ключа авторизации.
- Новые ключи можно выпускать без ограничения по частоте, но каждый ключ имеет свой лимит.
Ограничение текста
В одном запросе можно отправить текст длиной до 4096 символов. Пробелы и знаки препинания также учитываются как символы.
- Для длинных текстов рекомендуется разбивать их на части и объединять аудиофайлы на стороне клиента.
Очередь обработки
Запросы обрабатываются последовательно. При высокой нагрузке запрос может ожидаться в очереди, что увеличивает время ответа.
- Время генерации обычно соответствует реальному времени речи, но при загрузке сервера возможны задержки.
Структура ответа
API возвращает синтезированный аудиофайл напрямую в теле ответа. Формат данных зависит от параметра response_format, указанного в запросе (mp3, wav, opus, flac или pcm). Бинарные данные готовы к немедленному воспроизведению или сохранению на диск.
Ответ содержит стандартные HTTP-заголовки, такие как Content-Type, указывающие на тип файла. В отличие от потоковой передачи, аудио поступает целиком после завершения синтеза.
Бинарные данные
Тело ответа содержит сжатый или несжатый аудиофайл. Это позволяет сразу передавать контент в голосовые ассистенты без промежуточных конвертаций.
Заголовки ответа
Сервер возвращает заголовок Content-Type, соответствующий запрошенному формату. Это гарантирует корректную обработку файла клиентскими библиотеками.
Метаданные
В метаданных запроса учитывается количество использованных символов для биллинга. Если синтез не удался, возврат средств происходит автоматически.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Выбор голоса напрямую влияет на то, как пользователи воспринимают вашего бота.
23 языка
Любой голос может говорить на любом из этих языков.
