Часто задаваемые вопросы
Какой формат ответа у 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.mp3Python (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 | 中文 |
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-ключа
Для начала работы с 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
Для отправки текста на синтез используется 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
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 из одного и того же предложения. Его богатый низкий регистр придает контенту вес и авторитетность.
23 языка
Любой голос может говорить на любом из этих языков.
