Интеграция API синтеза речи: первый запрос и ключи

Автор Редакция Glasyar · Обновлено 2026-11-19

Эта страница поможет вам выполнить первый запрос к API синтеза речи Glasyar и получить аудиофайл. Мы подробно описываем процесс получения API-ключа, настройку параметров голоса и скорости, а также предоставляем готовые примеры на cURL. Вы узнаете, как правильно указывать язык и формат вывода, чтобы избежать ошибок при интеграции.

Документация предназначена для инди-разработчиков, которые внедряют голосовые уведомления в свои SaaS-продукты. Мы объясняем, как обрабатывать длинные тексты, разбивая их на части до 4096 символов, и как интерпретировать коды ответов API. Здесь нет лишней теории — только конкретные шаги для быстрого старта работы с нашим REST API.

Интеграция API синтеза речи: первый запрос и ключи

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

Какой формат ответа у API?

API возвращает аудиофайл в указанном формате: mp3, wav, opus, flac или pcm. Заголовок Content-Type соответствует выбранному формату. Тело ответа содержит бинарные данные аудио. Это позволяет легко интегрировать результат в плееры или сохранять файлы на диск без дополнительной обработки.

Как изменить base_url в SDK?

Используйте официальный SDK OpenAI, изменив параметр base_url на https://api.goud999.info/v1. Формат запроса идентичен стандартному эндпоинту speech. Это позволяет использовать существующие библиотеки без изменений логики. Ключ авторизации передается через заголовок Authorization: Bearer.

Поддерживается ли генерация в реальном времени?

Нет, потоковая генерация аудио или WebSocket не поддерживаются. API возвращает готовый аудиофайл после завершения синтеза. Для длинных текстов требуется разбивка на части до 4096 символов и последующее объединение файлов. Реакция зависит от очереди обработки запросов.

Можно ли указать язык явно?

Да, параметр language принимает ISO-код языка (например, ru, en). Если язык не указан, он определяется автоматически по скрипту текста. Для латиницы по умолчанию выбирается английский. Язык можно задать для любого из 8 доступных голосов.

Какие ошибки могут возникнуть?

Основные ошибки: превышение лимита запросов (429), неверный ключ (401), неверный формат ввода (400). Также возможны ошибки сервера (500). Сбои синтеза возвращаются с соответствующим статусом. Ошибки не списывают баланс, если синтез не выполнен.

Как обработать ответ с ошибками?

Проверяйте HTTP-статус ответа. При ошибке 429 ожидайте заголовки Retry-After. При 400 или 401 проверьте параметры запроса и ключ. Тело ответа содержит описание ошибки. Повторяйте запросы с экспоненциальной задержкой при временных сбоях сервера.

Сколько длится генерация аудио?

Скорость примерно равна реальному времени: 25 символов текста в секунду аудио. Короткие фразы генерируются за несколько секунд. При высокой нагрузке запросы могут стоять в очереди. Время зависит от длины текста и текущей загрузки сервера.

Поддерживаются ли аудиофайлы PCM?

Да, формат PCM поддерживается как один из вариантов response_format. Он возвращает необработанные аудиоданные. Это полезно для прямой обработки или записи в специфичные форматы. Другие поддерживаемые форматы: mp3, wav, opus, flac.

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

Отправьте любой запрос к API, например GET /v1/voices или POST /v1/audio/speech с коротким текстом. Если ключ валиден, вы получите ответ 200. При невалидном ключе вернется ошибка 401. Ключ должен начинаться с префикса tts-.

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

Да, API работает по HTTPS. Все запросы к https://api.goud999.info/v1 защищены SSL/TLS. Это стандартное требование для безопасной передачи данных и ключей авторизации. Убедитесь, что ваш клиент поддерживает современные версии TLS.

Есть ли rate limiting?

Да, лимит составляет 60 запросов в минуту на один ключ. До первого пополнения баланса лимит ниже — 10 запросов в минуту. При превышении лимита возвращается статус 429. Ограничения действуют на уровне ключа API.

Как узнать ID запроса?

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

Сколько стоит запрос при ошибке?

Неверные запросы бесплатны (списание не происходит). Если синтез не выполнен из-за ошибки, списание не происходит. Баланс не уменьшается за отклоненные или сбойные запросы. Вы платите только за успешно сгенерированные аудиофайлы.

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

curl

curl https://api.goud999.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.goud999.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.goud999.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-ключа

Для начала работы с Glasyar создайте аккаунт на странице /get-api-key/. Регистрация доступна через Google или по почте с паролем. Учетные записи, созданные по email, не получают пробный баланс. Учетные записи привязываются к домену goud999.info.

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

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

При входе через Google вы получите пробный баланс $0.50, действительный 7 дней. Если используете email и пароль, кредит не начисляется. Баланс не истекает, пополнение возможно только через USDT (TRC-20).

Генерация ключа

Генерация ключа

На панели аккаунта отобразится ваш API-ключ, начинающийся на tts-.... Один активный ключ на аккаунт. Используйте его в заголовке Authorization: Bearer для запросов к https://api.goud999.info/v1.

  • Ключ отображается на странице аккаунта.
  • Пароль: Authorization: Bearer tts-....

Смена ключа

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

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

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

Для отправки текста на синтез используется POST-запрос к конечной точке /v1/audio/speech. Тело запроса содержит обязательные поля: модель (tts-1 или tts-1-hd), текст (до 4096 символов) и идентификатор голоса. Аутентификация осуществляется через заголовок Authorization с токеном Bearer.

Базовый запрос

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

  • Endpoint: POST https://api.goud999.info/v1/audio/speech
  • Header: Authorization: Bearer YOUR_API_KEY
  • Body: JSON с полями model, input, voice, response_format

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

Обязательные поля включают model (tts-1 или tts-1-hd), input (текст) и voice (например, aria, nova, felix). Опционально можно указать response_format (mp3, wav, opus, flac, pcm) и speed (0.25–4.0). Поле language необязательно; если оно не указано, язык определяется по скрипту.

  • input: до 4096 символов
  • voice: один из 8 пресетов
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25–4.0
  • language: ISO код (опционально)

Обработка ответа

При успешном синтезе API возвращает аудиофайл в указанном формате. Если синтез не удался, запрос будет бесплатным, а средства возвращены на баланс. Убедитесь, что обрабатываете возможные HTTP-ошибки, такие как 429 (лимит запросов), 401 (неверный ключ) или 400 (неверный формат).

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

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

API Glasyar совместим с официальными SDK OpenAI. Это позволяет использовать знакомые инструменты для отправки запросов на синтез речи без необходимости писать собственную библиотеку для работы с нашим эндпоинтом.

Изменение base_url

Для подключения измените базовый URL в конфигурации SDK на https://api.goud999.info/v1. Это основное изменение, необходимое для маршрутизации запросов к нашему API вместо серверов OpenAI.

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

Используйте стандартные методы SDK, такие как audio.speech.create. Структура входных данных (model, input, voice) идентична формату OpenAI, поэтому логика вашего кода остается прежней.

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

Ниже приведен минимальный пример на Python. Он демонстрирует, как инициализировать клиент и отправить текст на синтез, получив аудиофайл в формате mp3.

  • from openai import OpenAI
  • client = OpenAI(base_url='https://api.goud999.info/v1', api_key='tts-...')
  • response = client.audio.speech.create(model='tts-1', voice='nova', input='Привет, мир!', response_format='mp3')

Форматы аудио

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

Формат вывода выбирается в поле response_format запроса. Выбор зависит от сценария воспроизведения: веб-плееры, запись файлов или минимизация трафика.

Синтез поддерживает MP3, WAV, OPUS и FLAC. Каждый формат оптимизирован под конкретные задачи интеграции.

MP3 для веба

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

Идеально подходит для SaaS-уведомлений, где важна скорость доставки аудио в браузерные плееры без дополнительной конвертации.

  • Совместимость с любыми современными браузерами
  • Минимальный размер файла для быстрой загрузки
  • Оптимальное соотношение качества и объема трафика

WAV для качества

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

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

  • Отсутствие потерь качества при сжатии
  • Подходит для локального хранения
  • Легкая обработка сторонним ПО

OPUS и FLAC для сжатия

OPUS предлагает эффективное сжатие с высоким качеством, что снижает расходы на трафик при сохранении разборчивости речи.

FLAC обеспечивает lossless-сжатие, уменьшая объем файла по сравнению с WAV без потери данных. Оба формата полезны для архивации или мобильных приложений с ограничениями по трафику.

  • OPUS: высокое сжатие с сохранением качества
  • FLAC: lossless-сжатие для архивов
  • Снижение затрат на трафик

Настройка голоса и скорости

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

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

Выбор пресета голоса

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

  • Женские: aria (повествование), nova (бодрая), luna (истории), sage (инструкции)
  • Мужские: felix (промо), milo (диалог), atlas (новости), orion (документальные)

Диапазон скорости 0.25–4.0

Параметр speed позволяет регулировать темп речи от очень медленного (0.25x) до ускоренного (4.0x). Это полезно для адаптации контента под разные нужды: от детального разбора до быстрых уведомлений.

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

Хотя система автоматически определяет язык по скрипту (по умолчанию — английский для латиницы), рекомендуется явно указывать поле language для текста на языках с латинским алфавитом, отличных от английского. Поддерживается 23 языка, включая русский, китайский и арабский.

Настройка голоса и скорости

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

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

API возвращает стандартные HTTP-коды для диагностики. 200 означает успех, 400 — ошибка формата запроса или невалидные параметры, 401 — неверный или истёкший API-ключ. Код 429 применяется при превышении лимитов, а 500 сигнализирует о временных проблемах на стороне сервера.

Коды ошибок HTTP

При ошибке 400 в ответе приходит JSON с описанием проблемы. Для 401 проверьте заголовок Authorization. Код 429 указывает на исчерпание квоты запросов.

  • 200 OK: Успешный синтез.
  • 400 Bad Request: Неверный формат JSON или параметры.
  • 401 Unauthorized: Неверный ключ.
  • 429 Too Many Requests: Превышен лимит.

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

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

Лимиты запросов

Лимит составляет 60 запросов в минуту на один ключ. До первого пополнения лимит снижен до 10 запросов в минуту. При превышении API возвращает 429. Очередь обработки не учитывается в лимите, но может задерживать ответ.

  • Стандартный лимит: 60 req/min.
  • Лимит для новых аккаунтов: 10 req/min.
  • Лимит на ключ, а не на IP.

Работа с длинными текстами

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

API принимает текст до 4096 символов за один запрос. Для более дливых материалов требуется клиентская логика: разделение текста на фрагменты, последовательный синтез и объединение результатов в один аудиофайл.

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

Разбиение на части

Разбивайте текст на блоки не более 4096 символов. Символы пробела и пунктуации учитываются в лимите.

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

  • Максимум 4096 символов на POST-запрос.
  • Пробелы и знаки препинания входят в лимит.

Сборка аудиофайлов

Полученные аудиофрагменты объединяются в последовательности. Формат выходного файла соответствует указанному в параметре response_format.

При конвертации убедитесь, что тайминги фрагментов совместимы для бесшовного склеивания.

Ограничение 4096 символов

Превышение лимита вернет ошибку. Разделяйте текст программно до отправки в API.

Для текстов свыше 4096 символов потребуется несколько запросов к эндпоинту /v1/audio/speech.

Тестирование и отладка

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

Для отладки интеграции используйте панель управления на странице /get-api-key/. Там отображается текущий баланс, остаток символов и история запросов с указанием времени, статуса и количества обработанных символов. Это позволяет отслеживать расход средств и выявлять проблемы с генерацией.

Проверка баланса

Баланс обновляется автоматически после пополнения USDT (TRC-20) в течение нескольких минут. Остаток бесплатных символов trial-аккаунта виден сразу после регистрации. Отображение доступно в личном кабинете без дополнительных вызовов API.

Просмотр истории запросов

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

Валидация ключа

Убедитесь, что заголовок Authorization: Bearer tts-... передается корректно. Один активный ключ на аккаунт; при выпуске нового старый блокируется мгновенно. Используйте пример curl со страницы API-ключа для первичной проверки соединения.

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

Каждый образец ниже сгенерирован этим API из одного и того же предложения. Его богатый низкий регистр придает контенту вес и авторитетность.

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

23 языка

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

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

  1. Wikipedia
  2. IETF RFC 7845: Ogg Opus
  3. TRON developer hub: TRC-20
  4. LibriTTS-R corpus (OpenSLR 141)
  5. curl documentation
  6. Node.js documentation
  7. FFmpeg documentation
  8. Python documentation
  9. MDN: Web Speech API
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. Creative Commons Attribution 4.0
  12. ISO 639 language codes

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