Freedom Speech Realtime API

Голосовой агент «речь в речь», совместимый по протоколу с OpenAI Realtime API. Клиент, который уже работает с OpenAI Realtime, подключается к нам сменой адреса и ключа.

Обзор

• Как работает. Вы открываете WebSocket, передаёте свои инструкции и инструменты (function calling) и шлёте звук собеседника. Агент отвечает голосом и текстом и вызывает ваши инструменты. Исполняете их вы и возвращаете результат.
• Разговор без пауз. Пока агент ищет данные или думает над ответом, он сразу поддерживает разговор короткой фразой («Сейчас посмотрю»), чтобы собеседник не слушал тишину.
• Страховка от лишних действий. Перед инструментом, который что-то меняет (отмена, перевод, запись), агент спрашивает подтверждение, даже если инструкции этого не требуют. Инструменты чтения (найти заказ, узнать статус) вызываются сразу.
• Где работает. Все модели работают на наших GPU-серверах. Сторонние AI-провайдеры в обработке разговора не участвуют, звук и текст разговоров не сохраняются.
• Статус. Тестовый доступ для партнёров, без SLA.

Быстрый старт

Для старта нужны три вещи:

Пример на стоковом SDK openai для Python (версия 2.x, GA-диалект). Именно таким клиентом мы проверяли сервис: звук PCM16 24 кГц моно, кусками по 20 мс, инструменты исполняет клиент.

import asyncio, base64, json
from openai import AsyncOpenAI

TOOLS = [{
    "type": "function", "name": "get_order",
    "description": "Статус заказа по номеру",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]},
}]

async def main(pcm_chunks):  # pcm_chunks: куски PCM16 24 кГц по 20 мс (960 байт)
    client = AsyncOpenAI(api_key="<КЛЮЧ>",
                         websocket_base_url="wss://realtime.freedomspeech.kz/v1")
    async with client.realtime.connect(model="local") as conn:
        await conn.session.update(session={
            "type": "realtime",
            "instructions": "Ты оператор службы доставки. Отвечай коротко, по-русски.",
            "tools": TOOLS,
            "audio": {"input":  {"format": {"type": "audio/pcm", "rate": 24000}},
                      "output": {"format": {"type": "audio/pcm", "rate": 24000}}},
        })

        async def reader():
            async for ev in conn:
                if ev.type == "response.output_audio.delta":
                    play(base64.b64decode(ev.delta))          # ваш плеер
                elif ev.type == "conversation.item.input_audio_transcription.completed":
                    print("клиент:", ev.transcript)
                elif ev.type == "response.output_audio_transcript.done":
                    print("агент:", ev.transcript)
                elif ev.type == "response.function_call_arguments.done":
                    result = call_my_backend(ev.name, json.loads(ev.arguments or "{}"))
                    await conn.conversation.item.create(item={
                        "type": "function_call_output", "call_id": ev.call_id,
                        "output": json.dumps(result, ensure_ascii=False)})
                    await conn.response.create()
                elif ev.type == "error":
                    print("ошибка:", ev.error)

        task = asyncio.create_task(reader())
        for chunk in pcm_chunks:                      # звук идёт постоянно,
            await conn.input_audio_buffer.append(       # в том числе тишина
                audio=base64.b64encode(chunk).decode())
            await asyncio.sleep(0.02)
        task.cancel()

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

Подключение и авторизация

Полный адрес WebSocket: wss://realtime.freedomspeech.kz/v1/realtime?model=local. Список доступных моделей: GET https://realtime.freedomspeech.kz/v1/models с тем же ключом.

Ключ передаётся одним из двух способов, как у OpenAI:

• заголовок Authorization: Bearer <ключ> — для серверных клиентов;
• подпротокол WebSocket openai-insecure-api-key.<ключ> — если заголовки задать нельзя.

Из браузера напрямую не подключиться. Сервер отвечает 403 на любой чужой заголовок Origin. Ставьте ретранслятор на своём бэкенде: он добавляет ключ и не передаёт Origin. Так ключ и не попадёт в браузер.

Диалект. Поддерживаются оба: beta (openai < 2.0, Azure) и GA (openai ≥ 2.0, livekit-plugins-openai ≥ 1.6).

• Заголовок OpenAI-Beta не читается.
• Соединение начинается в beta. На GA оно переключается навсегда, когда приходит первый session.update с полем type или audio.
• Поэтому первое событие session.created всегда приходит в beta-форме. Стоковый SDK это переносит.

Ошибки подключения. Это обычные HTTP-ответы до установки WebSocket:

JSON-ошибки имеют вид {"error": {"type", "code", "message"}}.

Закрытие соединения. Ошибки в событиях соединение не рвут, они приходят событием error. Сам сервер закрывает WebSocket только в трёх случаях:

• 1000 — сессия завершена;
• 1001 — сервер останавливается;
• 1008 — клиент не забирает события дольше 20 с.

Настройка сессии (session.update)

Первый session.update запускает разговор, поэтому шлите его сразу после session.created. Повторные session.update работают по ходу разговора.

Аудиоформаты (вход и выход задаются независимо):

• Моно, base64 в input_audio_buffer.append.
• Размер куска любой: неполные кадры склеиваются. Рекомендуем 20–100 мс в реальном времени.
• Один кусок — не больше 15 МБ.

События

Названия событий и их поля совпадают с OpenAI Realtime. Неизвестный type от клиента даёт error с code: unknown_event, соединение при этом не рвётся.

Клиент → сервер

Сервер → клиент. Названия приведены в GA; в beta — response.audio.*, response.audio_transcript.*, conversation.item.created.

Не приходят: response.output_text.* (текстового режима нет), response.content_part.*, output_audio_buffer.*, rate_limits.updated, conversation.item.retrieved.

Несколько деталей:

• В response.done у прерванного ответа status: cancelled, status_details.reason: turn_detected.
• usage может отсутствовать.
• Итоговая расшифровка может содержать пометки звуков и интонации. Чистый текст лежит в поле text_plain.

Вызов инструментов

Инструменты описываются и возвращаются так же, как в OpenAI Realtime. Исполняете их вы.

Последовательность:

1. Агент решает вызвать инструмент. Вы получаете response.output_item.added → conversation.item.added → response.function_call_arguments.delta → response.function_call_arguments.done (с call_id, name, arguments) → response.output_item.done.
   • Аргументы приходят целиком одним delta, а не по кускам.
   • Если вызов случился вне текущего ответа, он приходит в отдельной паре response.created … response.done.
2. Вы исполняете вызов и шлёте conversation.item.create с {"type": "function_call_output", "call_id": …, "output": "<JSON-строка>"}.
3. Агент озвучивает ответ по результату.
   • response.create после результата можно слать, как с OpenAI, но не обязательно: без него агент заговорит сам через ~0,5 с.
   • Если response.create пришёл, пока агент ещё обдумывает результат, сервер сразу отвечает пустым response.created / response.done. Настоящий ответ придёт отдельным ответом.

Ошибки и таймауты.

• Результат-объект с "ok": false или непустым "error" агент считает ошибкой инструмента и не выдаёт его за успех.
• Если ответ не пришёл за 30 с, агент перестаёт ждать. Запоздавший результат всё равно учитывается дальше в разговоре.
• Пока инструмент работает, агент обычно говорит короткую связку («Сейчас посмотрю»). Держите инструменты быстрыми: на телефоне пауза дольше 2–3 с заметна.

Подтверждение действий. Это главное отличие от OpenAI в поведении.

• Инструменты, которые что-то меняют (имя вроде cancel_order, create_booking, transfer_money), агент вызывает только после явного согласия клиента: он переспрашивает и ждёт «да».
• На «нет» или неясный ответ вызов не делается. Вы его просто не получите.
• Инструменты чтения (имя вроде get_order, find_client, check_status) вызываются сразу.
• Тип инструмента агент определяет по имени и описанию. Сомнительный считается действием. Давайте инструментам понятные английские имена с глаголом. Если какой-то инструмент классифицируется неверно, напишите нам — поправим настройкой без изменений с вашей стороны.

Перебивания и очерёдность

Конец реплики и перебивания сервер определяет сам. Ручного режима (turn_detection: null) нет.

• Конец реплики. Определяет модель очерёдности по звуку и смыслу: обычно через 0,4–0,7 с тишины. Если реплика кончается цифрами (номер, телефон), сервер ждёт ~1,8 с — вдруг клиент продолжит диктовать.

• События реплики клиента. Идут в таком порядке:

  1. input_audio_buffer.speech_started.
  2. input_audio_buffer.speech_stopped.
  3. input_audio_buffer.committed.
  4. conversation.item.added.
  5. conversation.item.input_audio_transcription.completed.

  Если слов не распознано (кашель, шум), придёт только speech_stopped. - Перебивание. Если клиент во время речи агента сказал два и больше слова по делу, агент замолкает. Текущий ответ заканчивается response.done со статусом cancelled. - Короткое «ага», «угу», «да» считается поддакиванием и речь агента не останавливает. - Воспроизведение на вашей стороне. Как и с OpenAI, по speech_started или прерванному ответу очистите свой буфер воспроизведения. Чтобы история соответствовала тому, что клиент услышал, пошлите conversation.item.truncate с audio_end_ms. Сам сервер conversation.item.truncated без вашего запроса не шлёт. - Паузы клиента. По умолчанию агент не переспрашивает «Вы меня слышите?», если клиент долго молчит. Завершение звонка по тишине — на вашей стороне.

Лимиты, задержки, языки

Лимиты тестового доступа

Задержки. Замеряли на нашем стенде в ноябре 2026, по одному разговору за раз. Отсчёт от конца речи клиента.

Для сравнения: в том же замере gpt-realtime дал первый звук через ~1,6 с. Сеть туда и обратно от клиента в Алматы до нашего движка в замере занимала ~0,15 с.

Языки.

• Русский — основной, на нём проведены все проверки.
• Казахский поддержан: агент переходит на язык клиента, голос alua говорит по-казахски. Через этот API на казахском мы ещё не тестировали — проверьте на своих сценариях.
• Язык каждой реплики клиента приходит в поле language события conversation.item.input_audio_transcription.completed.

Отличия от OpenAI Realtime

Клиент OpenAI Realtime работает без доработок, если учесть пункты ниже. Самые важные стоят первыми.

Стоковый пакет openai для Python (GA) мы проверили на распознавании, инструментах и подтверждениях. Другие SDK (LiveKit, Pipecat, Twilio) по протоколу должны работать, но мы их не гоняли. Если что-то не стыкуется, пришлите лог событий.

Данные, безопасность, поддержка

• Записи разговоров не хранятся: ни звук, ни расшифровки, ни ваши инструкции. В технических логах остаются только время, тип событий и служебные решения агента, без текста реплик.
• Внешние сервисы не вызываются. Вся обработка речи и ответов идёт на наших серверах; исходящие соединения закрыты.
• Ваши инструменты исполняете вы. Мы видим только их описание и результат, который вы вернули в сессию. Доступов к вашим системам нам не нужно.
• Шифрование: только wss:// (TLS).
• Ключ. Храните на сервере. В браузер и мобильное приложение ключ не кладите: подключайтесь через свой бэкенд. Если ключ утёк, сообщите — заменим.
• Поддержка. Пишите вашему контакту в Freedom Speech: он выдаёт ключ и помогает с интеграцией. С вопросом присылайте время сессии (UTC) и session.id из первого события.