API endpoint, или конечная точка API, — это точный адрес, по которому API получает запросы и возвращает ответы. Это точка, в которой приложение подключается к серверу для запроса данных или запуска команды. В руководстве, опубликованном в своем блоге, компания ElevenLabs подробно описывает этот механизм на примере своего интерфейса ElevenAPI.
Запросы, ответы и маршруты
Конечная точка — это цифровое местоположение, которое API использует для получения запросов и отправки ответов. Клиентские приложения получают доступ к ресурсам сервера через URL, привязанный к этой конечной точке. Каждый маршрут связывает метод HTTP, протокол коммуникации в вебе, с путем к ресурсу.
Обмен обычно следует четырем этапам. Сначала клиент отправляет HTTP-запрос, включающий метод, заголовки, возможно, параметры и тело данных. Сервер проверяет учетные данные и права доступа, затем запрашивает свои базы данных или выполняет бизнес-логику. Затем он возвращает полезную нагрузку в формате JSON, структурированном формате данных, вместе с кодом состояния HTTP. Наконец, клиентское приложение использует эти данные.
Термины API, endpoint и URL часто используются вместе, но они обозначают разные вещи. API — это набор правил и контрактов данных, которые позволяют двум приложениям общаться. Endpoint — это конкретная точка входа, а URL — это полная письменная адресная строка, позволяющая найти его в сети. API содержит несколько конечных точек, а URL может включать протокол, доменное имя, путь и параметры запроса.
В REST API запросы GET читают данные, не изменяя ресурсы сервера, в то время как запросы POST создают их или запускают действия. Запросы PUT или PATCH служат для изменения существующих записей, а DELETE — для их удаления. Согласно руководству, ElevenAPI в основном полагается на GET и POST, к которым добавляются конечные точки для потоковой передачи и WebSocket для аудио в реальном времени. Например, запрос GET https://api.elevenlabs.io/v1/models получает список доступных моделей синтеза речи и их возможности. Запрос POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} отправляет текст и идентификатор модели и возвращает аудио в потоковом режиме.
Защита конечных точек
Каждый запрос передает секретный ключ в заголовке xi-api-key. Эти долгосрочные ключи должны храниться на защищенных серверах и никогда не появляться в клиентском коде, например, в браузере или мобильном приложении. Для клиентских WebSocket-подключений сервер генерирует одноразовый токен, который истекает через 15 минут и расходуется при первом использовании.
Руководство также рекомендует создавать отдельные ключи для разработки, предпродажной подготовки и продакшена. Каждый ключ может быть ограничен определенными конечными точками, например, только транскрипцией речи для ключа, которому не нужен синтез. Для ключей можно устанавливать квоты кредитов, а корпоративные аккаунты могут ограничивать использование определенными IP-адресами — функция, представленная как находящаяся в предварительной версии. Запросы с другого адреса отклоняются с ошибкой HTTP 403. Ограничения скорости, согласно источнику, основаны на конкурентности, то есть количестве одновременных генераций, а не на квоте в минуту.
Тестирование и мониторинг
Тестирование конечной точки с самого начала позволяет проверить аутентификацию и подключение до написания прикладной логики. Запрос GET к https://api.elevenlabs.io/v1/models с заголовком xi-api-key достаточен для проверки учетных данных и сетевого доступа. Согласно руководству, этот тест не расходует кредиты, списываемые со счета.
Также необходимо отслеживать ошибки HTTP 429. Ошибка too_many_concurrent_requests означает, что аккаунт достиг лимита конкурентности своего тарифа: нужно дождаться завершения текущих запросов или перейти на более высокий тариф. Ошибка system_busy, напротив, указывает на временную перегрузку платформы, и повторная попытка обычно успешна.
