API Guides
Direct API Overview
Decide when to call HUMAIN Voice without an SDK and pick the batch REST, HTTP streaming, or Socket.IO transport for each workflow.
When to call the API directly
The JavaScript and Python SDKs wrap batch REST and Socket.IO. Call the API yourself when:
- your language has no SDK;
- your runtime can't keep a WebSocket open, so you need the HTTP streaming routes, which no SDK calls;
- you need a wire feature the SDKs don't expose, such as the Socket.IO diarization tee that returns live text and speakers from one stream.
Every transport authenticates with x-api-key from a backend (Socket.IO also needs an Origin
header); see Authentication. To pick the workflow itself, see
Concepts.
Transports by workflow
| Workflow | Transport | Guide |
|---|---|---|
| Batch transcription | REST: submit a job, then poll | Batch REST |
| Fast transcription | Socket.IO audio_file, or HTTP stt | Socket.IO · HTTP streaming |
| Realtime transcription | Socket.IO audio_stream, or HTTP stt-stream | Socket.IO · HTTP streaming |
| Live diarization | Socket.IO diarization_stream (or the tee on audio_stream), or HTTP diarization-stream | Socket.IO · HTTP streaming |
| Text to speech | Socket.IO tts: playable 24 kHz PCM, or HTTP tts: a framed 16 kHz capture you can't reliably play, or POST /v1/audio/speech: one complete MP3/WAV/PCM file (on voice-dev today) | Socket.IO · HTTP streaming · OpenAI-compatible speech |
For live audio, Live audio over the API compares Socket.IO with HTTP streaming. Error codes, limits, and retry rules for every transport are in Errors and limits.
Specifications
| Surface | Reference |
|---|---|
| Batch REST (OpenAPI) | Batch API reference |
| HTTP streaming (OpenAPI) | Realtime HTTP API reference |
| Socket.IO (AsyncAPI) | Realtime · Fast transcription · TTS events |
Markdown copies of every page are listed on the Introduction.