---
title: Direct HTTP API Reference
icon: BookOpen
description: 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](/en/quickstart) or [API Guides](/en/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](/en/authentication) before exposing an integration to users.

```bash
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:

```bash
curl --include "$API_URL/v1/transcribe/00000000-0000-4000-8000-000000000000" \
  --header "x-api-key: $API_KEY" \
  --header "Origin: $API_URL"
```

- `404` is compatible with lookup of the unknown job, but does not by itself prove that the credential and Batch capability are valid.
- `401` indicates that the key is missing or invalid for the request path.
- `403` indicates that access was denied; verify the configured values through your organization’s approved access flow.

## Reference sections

### [Batch API](/en/api-reference/batch)

Submit complete long-form recordings, then poll a job to a terminal state.

### [Realtime HTTP API](/en/api-reference/realtime-http)

Stream Fast, live ASR, diarization, or text-to-speech over HTTP.

## Operational boundaries

- A Batch submit can return `429` when 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`, or `cleared`.
- 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`](/en/api-reference/md) for this page as raw Markdown.
- Append an operation slug, such as [`/en/api-reference/md/batch/submit-transcription-job`](/en/api-reference/md/batch/submit-transcription-job), for one operation.
- Use [`/llms-full.txt`](/llms-full.txt) for the complete bilingual documentation bundle.

## Next steps

### [Authentication](/en/authentication)

Obtain, configure, and protect an API key.

### [API Guides](/en/api-guides)

Choose a protocol and follow its lifecycle.

### [Errors and rate limits](/en/api-guides/errors-and-rate-limits)

Classify failures and implement safe retries.