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

WorkflowTransportGuide
Batch transcriptionREST: submit a job, then pollBatch REST
Fast transcriptionSocket.IO audio_file, or HTTP sttSocket.IO · HTTP streaming
Realtime transcriptionSocket.IO audio_stream, or HTTP stt-streamSocket.IO · HTTP streaming
Live diarizationSocket.IO diarization_stream (or the tee on audio_stream), or HTTP diarization-streamSocket.IO · HTTP streaming
Text to speechSocket.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

SurfaceReference
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.

Next steps

On this page