Hydra (Realtime / WebSocket)

Hydra is Smallest AI’s full-duplex speech-to-speech model. A single WebSocket carries microphone audio from your client to the model and streams synthesised response audio back. Audio in, audio out. Hydra does not emit a transcript stream. If your application needs text, transcribe the PCM you sent or received using the Pulse STT API.

When to use this

• Use Hydra when latency-to-voice matters above all else (phone agents, kiosks, in-car assistants, real-time tutors).
• Use the Pulse → Electron → Lightning v3.1 stack when you need explicit text in the middle (analytics, custom RAG, regulated content moderation, BYOM).
• Use just Lightning v3.1 when you already have text and only need TTS.

Model versions

Three Hydra tags are served on this endpoint; select one with ?model=. Everything else in this reference (event catalog, session.configure shape, tool calling, interruption handling) is identical across them, so switching versions is a one-parameter change on the query string.

See the Deprecation Notices page and the Hydra model card for the per-version reference.

How it works

1. Connect: wss://api.smallest.ai/waves/v1/s2s?model=hydra-v1.1&api_key=<SMALLEST_API_KEY>.
2. Receive session.created → send session.configure with persona, voice, optional tools. On the deprecated ?model=hydra, a warning frame with code: "model_deprecated" arrives immediately before session.created.
3. Stream input_audio_buffer.append continuously while the mic is open, even while the model is speaking. Hydra detects turn boundaries on its own.
4. Read session.configured.session.output_audio_sample_rate and initialize your audio pipeline at that rate. Then receive response.output_audio.delta chunks (base64 PCM16) and queue them for playback.
5. Handle barge-in: if response.created arrives before the previous response’s response.output_audio.done, drop any still-scheduled audio buffers from the previous response.

Audio formats

• Input (client → server): PCM16, signed little-endian, mono, 16 kHz, base64 inside input_audio_buffer.append. Recommended chunk size 20–40 ms (640–1280 samples).

• Output (server → client): PCM16, signed little-endian, mono. Sample rate is per-model and echoed on session.configured.session.output_audio_sample_rate:

  • hydra-v1.0 outputs 48000 Hz
  • hydra-v1.1 outputs 24000 Hz

  Each chunk arrives base64-encoded inside response.output_audio.delta.

Voices

Set on session.configure.session.voice and frozen at handshake. Rosters are per version and do not overlap. When you switch versions, also pick a voice from the new roster.

• hydra-v1.1 (current release), ten voices: zoe, maya, elena, ivy, grace, alex, aria, leo, sam, kai.
• hydra-v1.0, fourteen voices: vaughn, brooks, cole, hayes, pierce, sterling, ellis, lane, quinn, arden, rowan, blair, emery, sawyer.
• hydra (original release, deprecated): migrate to one of the tags above and pick a voice from its roster.

Omit voice to use the server default voice. An unrecognised voice is rejected with an error frame (code: "invalid_request_error", param: "session.configure.session.voice") rather than silently defaulted. Validate client-side. The Hydra model card carries the per-version table.

Idle timeout

~30 seconds of no traffic from either side. Reconnect to resume.

Connection rejection and close codes

• Bad api_key is rejected during the WebSocket handshake with HTTP 401. The upgrade never completes, so no error event or close code lands on the wire.
• 1000. Normal close (including the ~30 s server-side idle timeout).
• 1013. Server at capacity. An error event with code: "server_full" precedes the close frame; back off with jitter and retry.

See the Hydra realtime guide for the full protocol reference, tool-calling pattern, interruption handling, and complete Python + browser examples.