Direct API Overview

Choose batch jobs, fast complete-audio, realtime streaming, or TTS for a direct HUMAIN Voice integration.

Use these guides when your runtime has no released SDK, you need wire-level control, or you need to diagnose transport behavior. JavaScript and Python apps should normally start with the SDK guides.

Choose by input lifecycle

Input and outcome	Direct surface	Start with	Keep open as the contract
A meeting, podcast, archive, or other long-form complete recording that can finish asynchronously	Batch REST: upload once, receive `jobId`, and poll	Batch REST guide	Batch OpenAPI
One complete latency-sensitive audio unit, such as a conversational turn	Fast transcription: send the whole unit through Socket.IO `audio_file` or HTTP multipart `/realtime/http/stt`	Socket.IO guide or Realtime HTTP guide	Fast AsyncAPI or Realtime HTTP OpenAPI
Audio that's still arriving, with live text or speaker segments	Realtime streaming: Socket.IO `audio_stream` / `diarization_stream`, or framed HTTP streaming	Realtime transport overview	Realtime AsyncAPI and Realtime HTTP OpenAPI
Text that must become speech	TTS: Socket.IO `tts` / `tts_audio`, or direct HTTP TTS with its documented framing limitation	Socket.IO guide; use Realtime HTTP only when your integration requires HTTP	TTS AsyncAPI or Realtime HTTP OpenAPI

Batch and fast transcription both consume complete audio. Choose batch for long-form media and fast only for a bounded complete unit whose latency matters. Result events don't make fast input realtime. Choose realtime only while audio is still arriving.

Long-form media: Batch REST

Submit one complete recording, poll with a deadline, and handle done, failed, and cleared.

Events: Socket.IO

Implement complete-audio fast STT, live STT, diarization, voice discovery, or framed TTS.

No Socket.IO: Realtime HTTP

Use complete-file multipart or framed HTTP operations and respect the HTTP TTS boundary limitation.

Live lifecycle and recovery

Reconcile provisional results, end streams, and recover conservatively after a disconnect.

Shared prerequisites

Obtain the environment-specific API_URL and API_KEY through the documented access flow. The SDK defaults Socket.IO to /socket.io; don't infer an override from another environment.
Send x-api-key on every protected HTTP request and Socket.IO connection. Keep it in a trusted backend; browser code can't keep an API key secret.
Set finite connection, request, read, polling, and final-result deadlines. Validate HTTP status before parsing success, and close every stream or socket.

Surface	Required audio or output contract
Batch REST	One `multipart/form-data` file upload
Fast transcription	One complete encoded file in a Socket.IO packet or HTTP multipart request
Realtime ASR and diarization	PCM16 little-endian, 16 kHz, mono; each input body includes the documented 18-byte control header
Socket.IO TTS	Framed raw PCM16 little-endian, 24 kHz, mono; audio starts after the 17-byte frame header
HTTP TTS	Undelimited protocol capture whose conceptual frames carry 16 kHz PCM16; generic clients can't recover frame boundaries or playable audio

Guides and references answer different questions

Use	When you need
API guide	A transport choice, request sequence, lifecycle rules, result reconciliation, cleanup, and operational cautions
Generated OpenAPI reference	Exact HTTP path, method, authentication, parameters, body, status codes, and response schemas
Generated AsyncAPI reference	Exact Socket.IO event names, payload fields, binary byte layouts, and connection security

Read the guide first, then keep the matching generated reference beside your implementation. If they appear to disagree on direct wire behavior, treat the validated generated specification as the contract and report the guide drift.

Next steps

Verify the issued URL and key without uploading audio.
Choose one row in the preceding table and complete its smallest representative request.
Add structured error handling and bounded retry from Errors and Rate Limits.