Direct HTTP API Reference
Schema-level reference for Batch and streaming HTTP integrations.
Use this reference when you need exact HTTP paths, parameters, request bodies, response shapes, or generated request examples. For a guided integration with SDK 0.18.0, start with the Quickstart or API Guides.
Choose by input lifecycle
| Workflow | Input state | Best fit |
|---|---|---|
| Batch transcription | One complete, long-form recording | Meetings, podcasts, interviews, and archives processed as asynchronous jobs |
| Fast transcription | One complete, bounded audio unit | Latency-sensitive agent turns, voice commands, and short conversational utterances |
| Realtime ASR | Audio is still arriving | Live microphones, calls, and other streams that need partial and final results |
| Text to speech | Text input; audio output | Generate a PCM16 audio stream from text |
Configure access
Obtain an API key through your organization’s approved access flow. Keep the key on a trusted backend and use the host and route path configured for your environment. See Authentication before exposing an integration to users.
export API_URL="https://api.voice.humain.com"
export API_KEY="YOUR_API_KEY"| API | Base path |
|---|---|
| Batch API | /v1 |
| Realtime HTTP API | /realtime |
Send a safe request
A read-only lookup for a deliberately unknown job ID provides non-mutating diagnostic evidence without creating work:
curl --include "$API_URL/v1/transcribe/00000000-0000-4000-8000-000000000000" \
--header "x-api-key: $API_KEY" \
--header "Origin: $API_URL"404is compatible with lookup of the unknown job, but does not by itself prove that the credential and Batch capability are valid.401indicates that the key is missing or invalid for the request path.403indicates that access was denied; verify the configured values through your organization’s approved access flow.
Reference sections
Batch API
Submit complete long-form recordings, then poll a job to a terminal state.
Realtime HTTP API
Stream Fast, live ASR, diarization, or text-to-speech over HTTP.
Operational boundaries
- A Batch submit can return
429when audio-processing capacity is exhausted. Treat the response as backpressure and use the returned capacity data when it is present. - Do not blindly retry an ambiguous file upload. Record the request outcome in your job layer so a timeout cannot create duplicate work unnoticed.
- Use bounded polling for Batch jobs and stop on
done,failed, orcleared. - The HTTP and Socket.IO realtime surfaces have different framing and lifecycle rules. Follow the page for the transport you actually use.
Markdown and LLM access
- Use `/en/api-reference/md` for this page as raw Markdown.
- Append an operation slug, such as `/en/api-reference/md/batch/submit-transcription-job`, for one operation.
- Use `/llms-full.txt` for the complete bilingual documentation bundle.