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

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

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

Документация охватывает полный цикл использования API: от получения ключа доступа до обработки аудиофайлов. Описаны совместимость с OpenAI SDK, лимиты нагрузки и поддержка форматов MP3, WAV, OPUS и FLAC. Материал подготовлен для специалистов, которым необходима точная интеграция без лишних абстракций.

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

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

Какой формат запроса ожидает API?

API ожидает HTTP-запрос POST на endpoint /v1/audio/speech с телом в формате JSON. Структура запроса полностью совместима с OpenAI Speech API, что позволяет использовать стандартные библиотеки для интеграции без необходимости изучения проприетарного формата данных.

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

Нет, установка дополнительного SDK не требуется. Вы можете использовать официальные SDK OpenAI, просто изменив базовый URL на https://api.333d.info/v1. Также подойдет любой стандартный HTTP-клиент для отправки POST-запросов с JSON-телом и заголовком авторизации.

Как изменить базовый URL в OpenAI SDK?

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

Какие поля обязательны в запросе?

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

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

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

Как задать конкретный язык для текста?

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

Возвращает ли API аудиофайл или ссылку?

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

Как обрабатывать ошибки синхронизации?

Если синтез не удался, charge возвращается в полном объеме. Ошибки обрабатываются стандартным образом через HTTP-статусы и тело ответа. При высоких нагрузках запросы могут стоять в очереди, что увеличивает время ответа, но не приводит к потере данных.

Есть ли ограничение на размер файла?

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

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

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

Как получить список доступных моделей?

Используйте GET-запрос к эндпоинту /v1/models. Также информацию о моделях, голосах, языках и форматах можно получить через GET /v1/voices. Эти эндпоинты возвращают актуальный список доступных опций для текущей конфигурации API.

Что такое параметр response_format?

Параметр response_format определяет формат возвращаемого аудиофайла. Поддерживаются форматы mp3, wav, opus, flac и pcm. Выбор формата влияет на размер файла и совместимость с плеерами или бортовыми системами навигации, где будет воспроизводиться синтезированный голос.

Где найти примеры кода на Python?

Готовые примеры кода, включая curl-запросы и варианты для Python, доступны на странице /get-api-key/ после авторизации. Там же отображается ваш API-ключ, баланс и текущие лимиты, что позволяет сразу приступить к интеграции в ваши сервисы.

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

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

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

curl

curl https://api.333d.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.333d.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.333d.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 синтезу речи GlasNav открывается через регистрацию на странице /get-api-key/. Поддерживаются два метода авторизации: вход через аккаунт Google или создание учетной записи по электронной почте с паролем.

После завершения регистрации система автоматически генерирует уникальный API-ключ для вашего аккаунта. Ключ отображается на странице /get-api-key/. Этот токен используется для аутентификации всех последующих запросов к API.

Регистрация через Google или email

Регистрация через Google или email

Регистрация занимает не более минуты. Для аккаунтов, созданных по электронной почте, не предоставляется пробный кредит ($0.50).

  • Поддержка Google OAuth и стандартной формы регистрации
  • Мгновенный доступ к личному кабинету
  • Отсутствие пробного кредита при регистрации по email

Генерация ключа доступа

Генерация ключа доступа

API-ключ генерируется один раз при создании аккаунта. Он отображается в интерфейсе сайта в разделе управления ключами. Ключ имеет формат tts-... и используется в заголовке Authorization: Bearer <ключ> при отправке POST-запросов.

  • Уникальный идентификатор для аутентификации
  • Отображение в личном кабинете после входа

Ограничение на количество активных ключей

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

  • Максимум один активный ключ на аккаунт
  • Мгновенная инвалидация старого ключа при выдаче нового

Первый запрос: генерация аудио

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

Для генерации аудио отправьте POST-запрос на endpoint https://api.333d.info/v1/audio/speech. Сервер принимает JSON-тело и возвращает аудиофайл в указанном формате. Это стандартный запрос, совместимый с экосистемой OpenAI SDK.

Базовая структура JSON-запроса

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

  • Метод: POST
  • URL: https://api.333d.info/v1/audio/speech
  • Content-Type: application/json

Необходимые поля: model, input, voice

Поле model принимает значения tts-1 или tts-1-hd. Поле input содержит текст до 4096 символов. Поле voice указывает один из 8 доступных пресетов (например, aria, atlas).

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

Пример cURL команды для теста

Выполните следующую команду в терминале, заменив YOUR_API_KEY на ваш ключ из личного кабинета.

Команда возвращает аудиофайл output.mp3.

  • curl -X POST https://api.333d.info/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Навигация активирована", "voice": "atlas"}' \
  • -o output.mp3

Использование OpenAI SDK

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

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

Изменение base_url на наш домен

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

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

Используйте метод audio.speech, передавая текст, голос и формат ответа. Структура JSON-запроса идентична стандартной, что упрощает отладку и поддержку кода в крупных командах.

Совместимость с библиотеками Python и JS

Библиотеки для Python и JavaScript работают без дополнительных адаптеров. Вы можете использовать один и тот же API-ключ для тестирования и production-разработки в разных средах.

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

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

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

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

MP3 для экономии трафика

Формат MP3 обеспечивает сжатие с потерями, что значительно снижает размер файлов. Это оптимальное решение для устройств с ограниченным объемом памяти и медленным интернет-соединением в автомобиле.

WAV для высокого качества

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

OPUS и FLAC для специфичных задач

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

Параметры запроса и ограничения

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

API синтезирует текст в аудиофайл, принимая JSON-запрос на POST https://api.333d.info/v1/audio/speech. Ключевые параметры позволяют адаптировать вывод под технические требования бортовых систем и навигационных сервисов.

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

Длина текста до 4096 символов

Поле input ограничено 4096 символами. Пробелы и знаки пунктуации учитываются как символы. Для длинных текстов (например, инструкций или навигационных подсказок) необходимо разбивать текст на части и объединять результирующие аудиофайлы.

Настройка скорости от 0.25 до 4.0

Параметр speed регулирует темп речи от 0.25 до 4.0. Это позволяет регулировать темп речи.

Ограничение 60 запросов в минуту

Лимит составляет 60 запросов в минуту на один API-ключ (10 до первого пополнения). Запросы обрабатываются по очереди, поэтому при высокой нагрузке возможно ожидание в очереди.

Параметры запроса и ограничения

Обработка ошибок и статусов

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

API возвращает стандартные HTTP-коды, указывающие на статус обработки запроса. Коды 2xx означают успешную генерацию аудиофайла, а 4xx и 5xx сигнализируют об ошибках валидации или временных сбоях сервера. При получении кода 5xx рекомендуется реализовать повторную попытку (retry) с экспоненциальной задержкой.

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

Коды ответа HTTP

Статус 200 OK сопровождается бинарными данными аудиофайла в указанном формате. Статус 400 Bad Request возникает при превышении лимита в 4096 символов или неверном формате JSON. Статус 429 Too Many Requests возвращается при исчерпании квоты в 60 запросов в минуту.

  • 200 OK — успешная генерация.
  • 400 Bad Request — ошибка валидации данных.
  • 401 Unauthorized — неверный API-ключ.
  • 429 Too Many Requests — лимит запросов исчерпан.

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

Если сервер не смог обработать запрос (ошибки 5xx) или запрос был отклонен до начала синтеза, средства за него возвращаются на баланс. Возврат происходит автоматически.

Эта логика защищает бюджеты крупных команд от необоснованных списаний при временных перегрузках сети или сервера.

Логирование запросов для биллинга

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

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

Управление голосами и языками

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

Эндпоинт GET /v1/voices предоставляет метаданные о доступных голосах и языках без генерации аудио. Это позволяет заранее интегрировать список доступных вариантов в интерфейсы бортовых систем или панели управления, исключая ошибки при выборе voice или language.

Эндпоинт GET /v1/voices

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

Получение списка доступных голосов

Ответ содержит идентификаторы восьми предустановленных голосов (например, aria, nova, atlas). Для автомобильной отрасли наиболее подходят atlas (нейтральный, новостной стиль) и milo (дружелюбный, разговорный), так как они обеспечивают четкую артикуляцию.

  • Идентификаторы голосов используются в поле voice запроса.
  • Каждый голос имеет описание тональности для точного подбора под тип контента.

Проверка поддержки языков

Система поддерживает 23 языка. Если поле language не указано, язык определяется автоматически по скрипту (латиница по умолчанию — английский). Для специфичных языков с латиницей или сложных сценариев рекомендуется явно указывать код языка (например, ru, de, en).

  • Поддерживаемые языки: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.

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

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

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

Отладка лимитов и параметров гарантирует стабильность работы при нагрузке. Проверка входных данных позволяет избежать ошибок генерации и лишних расходов бюджета.

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

Для локальной проверки используйте тексты до 4096 символов, соответствующие лимиту одного запроса. Отправляйте короткие фразы через cURL или SDK, чтобы убедиться в корректности формирования аудиофайла и отсутствия ошибок парсинга.

Тестируйте различные форматы (mp3, wav, opus) для оценки совместимости с вашими медиа-плеерами. Убедитесь, что метаданные запроса корректно логируются для последующего биллинга.

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

Проверка лимитов скорости

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

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

  • Лимит: 60 запросов/мин (10 до пополнения).
  • Обработка в очереди при высокой нагрузке.
  • Мониторинг статуса ответа HTTP.

Валидация входных параметров

Убедитесь, что поле input не превышает 4096 символов. Поля model, voice и response_format должны соответствовать поддерживаемым значениям из эндпоинта GET /v1/voices. Ошибка в параметрах приведет к немедленному отклонению запроса без списания средств.

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

  • Максимальная длина текста: 4096 символов.
  • Валидация ID голоса из списка API.
  • Проверка кода языка для латиницы.

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

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

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

23 языка

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

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

  1. Wikipedia
  2. W3C WAI: making audio and video accessible
  3. IETF RFC 7845: Ogg Opus
  4. curl documentation
  5. Node.js documentation
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. TRON developer hub: TRC-20
  8. LibriVox public-domain audiobooks
  9. FFmpeg documentation
  10. OpenAI API reference: create speech
  11. openai-python on GitHub
  12. LibriTTS-R corpus (OpenSLR 141)

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