Conventions
- Base URL
https://api.soundhalo.com. OpenAPI 3.1: /v1/openapi.json. - Examples use
$SOUNDHALO_API_KEYfor your key. Real tokens and request ids in the examples are replaced withatok_REDACTED,jtok_REDACTEDandreq_REDACTED. - Responses use the envelope
{ request_id, status, operation, result, job, receipt, warnings }. Readwarnings: it tells you about lines left out, sped-up speech and similar. - Money is in micro-dollars (1,000,000 = $1). "Balance" means your prepaid balance in dollars.
- Times are seconds (
start_sec,end_sec,duration_sec). Lines and cues must be in time order. - "Uses" names the allowance a call counts against. Daily allowances reset at midnight UTC; monthly ones on the first day of the month (UTC). Paid provider calls also count toward your plan's monthly cost cap. Numbers per plan are on Limits and pricing.
Files (assets)
Most calls work on a stored file, called an asset. Upload once, then pass its asset_ref (asset_id plus asset_token) to other calls. Every output file is an asset too.
POST /v1/assets
- Auth
- API key (or none, with anonymous limits)
- Uses
- One of the plan's daily uploads (Free 3, Starter 15, Pro 50, Creator 100, Business 250).
Send one file as multipart/form-data in the field file. Or send JSON {"source_url": "https://..."} to import a public https link instead. The server accepts up to 500 MB, but requests pass through Cloudflare, which limits request bodies, so keep direct uploads under 100 MB.
curl https://api.soundhalo.com/v1/assets \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-F "file=@interview.mp3" {
"request_id": "req_...",
"status": "completed",
"operation": "assets.create",
"result": {
"asset_ref": { "asset_id": "ast_...", "asset_token": "atok_..." },
"file_info": { "filename": "interview.mp3", "mime_type": "audio/mpeg", "size_bytes": 1048576 }
},
...
} Over the daily limit (a real response):
{
"request_id": "req_REDACTED",
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Daily upload limit of 3 files exceeded",
"details": {},
"retryable": true
}
} GET /v1/assets/:id
- Auth
- x-asset-token header
- Uses
- Nothing.
Returns the file's metadata in result.asset.
curl https://api.soundhalo.com/v1/assets/ast_... \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "x-asset-token: atok_..." GET /v1/assets/:id/download
- Auth
- x-asset-token header
- Uses
- Nothing.
Returns the file bytes. Output files carry this address as download_url.
curl -o dub.mp3 \
-H "x-asset-token: atok_..." \
https://api.soundhalo.com/v1/assets/ast_.../download DELETE /v1/assets/:id
- Auth
- x-asset-token header
- Uses
- Nothing.
Deletes the stored file, its metadata and access. Returns {"deleted": true}. Without this, access ends 30 days after the file was created (longer on paid plans, up to a year).
curl -X DELETE https://api.soundhalo.com/v1/assets/ast_... \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "x-asset-token: atok_..." Account and usage
GET /v1/usage/processing
- Auth
- API key
- Uses
- Nothing. A snapshot, not a promise that the next call will be accepted.
Fields for an account:
plan:free,starter,pro,creatororbusiness.dubbing:remaining_seconds,monthly_seconds,resets_at.lip_sync_included: Standard lip-sync seconds left this month.credits: your prepaid balance.balance_micros,next_expiry,next_expiry_micros. The field is calledcreditsfor historical reasons; it is the balance in micro-dollars.speech: transcription seconds left today and the longest file allowed.transform: processing seconds and jobs left today.synthesis: text to speech and voice-over characters left today, and the most per request.clone: cloned-voice cost left today in micro-dollars, and the most bytes per request.monthly:remaining_percentof the plan's monthly cost cap.
curl https://api.soundhalo.com/v1/usage/processing \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" GET /v1/me/billing/status
- Auth
- API key
- Uses
- Nothing.
Your plan and subscription status. Starting a payment is only possible on the signed-in page.
Transcription and jobs
POST /v1/extract/transcribe
- Auth
- API key (or none, with anonymous limits)
- Uses
- Transcription seconds per day and the plan's longest file. Monthly cost cap. Never the balance.
Options: language (default auto), timestamps (segment or word), diarize (speaker labels, true or false) and vocabulary (up to 100 short terms such as brand names, to help spelling). The text is a draft from a speech recognition model; check it before you publish it.
Without a header the call waits and returns the transcript in result (text, segments, detected_language, duration_sec). For long files send X-Execution-Mode: async to get a job back at once:
curl -X POST https://api.soundhalo.com/v1/extract/transcribe \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "X-Execution-Mode: async" \
-H "Content-Type: application/json" \
-d '{"input":{"asset_ref":{"asset_id":"ast_6e64b0faaeaf86bbbce16fc2fe6fdea5","asset_token":"atok_REDACTED"}},"options":{"language":"auto","timestamps":"segment"}}' {
"request_id": "req_REDACTED",
"status": "queued",
"operation": "extract.transcribe",
"result": null,
"job": {
"job_id": "job_7dbceef5aca5b6b27848e719a18a8f69",
"operation": "extract.transcribe",
"status": "queued",
"progress": null,
"created_at": "2026-11-16T02:02:58.484Z",
"updated_at": "2026-11-16T02:02:58.484Z",
"input_asset_ids": [
"ast_6e64b0faaeaf86bbbce16fc2fe6fdea5"
],
"output_asset_ids": [],
"warnings": [],
"result": null,
"job_token": "jtok_REDACTED"
},
"receipt": null,
"warnings": []
} GET /v1/jobs/:id
- Auth
- x-job-token header
- Uses
- Nothing.
Statuses: queued, running, succeeded, failed, cancelled, failed_partial. Check every few seconds, or subscribe to the job.completed and job.failed webhooks.
curl https://api.soundhalo.com/v1/jobs/job_7dbceef5aca5b6b27848e719a18a8f69 \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "x-job-token: jtok_REDACTED" {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "jobs.get",
"result": {
"job": {
"job_id": "job_7dbceef5aca5b6b27848e719a18a8f69",
"operation": "extract.transcribe",
"status": "succeeded",
"progress": null,
"created_at": "2026-11-16T02:02:58.484Z",
"updated_at": "2026-11-16T02:03:08.920Z",
"input_asset_ids": [
"ast_6e64b0faaeaf86bbbce16fc2fe6fdea5"
],
"output_asset_ids": [],
"warnings": [],
"result": {
"text": "Welcome to Sound Halo. This short recording tests the dubbing API. Each line should come back in Spanish, spoken by a new voice.",
"segments": [
{
"start_sec": 0.06,
"end_sec": 2.9,
"text": "Welcome to Sound Halo. This short recording"
},
{
"start_sec": 2.98,
"end_sec": 8.86,
"text": "tests the dubbing API. Each line should come back in Spanish, spoken by a new voice."
}
],
"detected_language": "en",
"duration_sec": 8.928,
"transcript_id": "tr_b2e94c381431a328a1e3b2f1c5c06497"
}
}
},
"job": null,
"receipt": null,
"warnings": []
} POST /v1/jobs/:id/cancel
- Auth
- x-job-token header
- Uses
- Gives the allowance back only if the job had not started yet.
A job that already reached a provider stays counted, and the provider may still finish it.
Caption translation
POST /v1/translate/captions
- Auth
- API key (or none, with anonymous limits)
- Uses
- Translation characters and files per day, and the plan's characters per file. Monthly cost cap. Never the balance.
Send up to 5,000 cues (start_sec, end_sec, text, up to 1,000 characters each). Times and order come back unchanged. Options: target_language (for example es-419, fr, de), glossary (terms to keep or translate the same way, one per line, up to 1,000 characters), glossary_mode (smart or strict), instructions (short style notes such as "informal") and purpose (subtitles, or dubbing for plain lines that fit each cue's time when read aloud). Translation is done by an AI model (DeepSeek through OpenRouter) and can contain mistakes.
curl -X POST https://api.soundhalo.com/v1/translate/captions \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"cues":[{"start_sec":0.06,"end_sec":2.9,"text":"Welcome to Sound Halo. This short recording"},{"start_sec":2.98,"end_sec":8.86,"text":"tests the dubbing API. Each line should come back in Spanish, spoken by a new voice."}]},"options":{"target_language":"fr","purpose":"subtitles"}}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "translate.captions",
"result": {
"target_language": "fr",
"cues": [
{
"start_sec": 0.06,
"end_sec": 2.9,
"text": "Bienvenue sur Sound Halo. Ce court enregistrement"
},
{
"start_sec": 2.98,
"end_sec": 8.86,
"text": "teste l'API de doublage. Chaque ligne devrait revenir en espagnol, prononcée par une nouvelle voix."
}
],
"characters": 127,
"provider": "openrouter",
"model": "deepseek/deepseek-v4.1-flash",
"usage": {
"requests": 1,
"input_tokens": 264,
"output_tokens": 66
}
},
"job": null,
"receipt": null,
"warnings": []
} Speech, voice-over, mix
GET /v1/generate/speech/voices
- Auth
- None
- Uses
- Nothing.
Lists the 92 catalog voices in 26 languages, each with id, name, language, gender, accent and sample_url, plus the languages and the limits. A voice's language is the language it speaks.
curl https://api.soundhalo.com/v1/generate/speech/voices POST /v1/generate/speech
- Auth
- API key (or none, with anonymous limits)
- Uses
- Text to speech characters per day (shared with voice-over) and the plan's characters per request. Cloned voice: cloned-voice cost per day instead. Never the balance.
Options: voice (a catalog id, or personal for your cloned voice, which also needs language) and format (mp3 or wav). The output is marked as synthetic speech.
curl -X POST https://api.soundhalo.com/v1/generate/speech \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"text":"Welcome to SoundHalo. This short recording tests the dubbing API. Each line should come back in Spanish, spoken by a new voice."},"options":{"voice":"en-US-michael","format":"mp3"}}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "generate.speech",
"result": {
"output_asset": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"asset_token": "atok_REDACTED",
"mime_type": "audio/mpeg",
"size_bytes": 107543,
"duration_sec": 8.874,
"download_url": "https://api.soundhalo.com/v1/assets/ast_6e64b0faaeaf86bbbce16fc2fe6fdea5/download"
},
"characters": 127,
"format": "mp3",
"synthetic": true,
"voice": {
"id": "en-US-michael",
"name": "Michael",
"language": "en-US"
}
},
"job": null,
"receipt": null,
"warnings": []
} POST /v1/compose/voice-over
- Auth
- API key (or none, with anonymous limits)
- Uses
- Text to speech characters per day and lines per request. With purpose dubbing: also dubbing minutes, then the balance up to max_balance_micros.
Turns timed lines (input.segments, up to 500 depending on plan) into one voice track. Each line starts at its start_sec. A line that is too long for its slot is sped up to at most 1.25 times, then flagged in summary.line_overrun_sec; words are never cut.
Options: voice, format, min_duration_sec (pad the track to at least this length), purpose (voice-over or dubbing), max_balance_micros (dubbing only: the most the balance may pay) and request_id (a retry key: repeating a request with the same id is refused with 409 instead of charged again). For a full dub, the dubbing API does these steps for you.
curl -X POST https://api.soundhalo.com/v1/compose/voice-over \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"segments":[{"start_sec":0,"end_sec":2.5,"text":"Bonjour et bienvenue."},{"start_sec":3,"end_sec":6,"text":"Cette piste a été créée avec l'API SoundHalo."}]},"options":{"voice":"fr-siwis","format":"mp3"}}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "compose.voice-over",
"result": {
"output_asset": {
"asset_id": "ast_98f2af6078e0893308de760363107e46",
"asset_token": "atok_REDACTED",
"mime_type": "audio/mpeg",
"size_bytes": 87667,
"duration_sec": 5.391,
"download_url": "https://api.soundhalo.com/v1/assets/ast_98f2af6078e0893308de760363107e46/download"
},
"summary": {
"line_count": 2,
"characters": 66,
"duration_sec": 5.391,
"sped_up_count": 0,
"overrun_count": 0,
"max_tempo": 1.25,
"providers": [
"lemonfox"
],
"line_tempo": [
1,
1
],
"line_overrun_sec": [
0,
0
]
},
"synthetic": true,
"voice": {
"id": "fr-siwis",
"name": "Siwis",
"language": "fr"
}
},
"job": null,
"receipt": null,
"warnings": []
} POST /v1/compose/mix
- Auth
- API key (or none, with anonymous limits)
- Uses
- Processing seconds and jobs per day for the longer of the two files. No provider cost, never the balance.
Lays a voice track (input.voice) over a recording or video (input.source). options.mode: duck lowers the original by about 15 dB under the voice, light-duck lowers it a few dB, replace drops the original sound. A video keeps its picture and comes back as MP4.
curl -X POST https://api.soundhalo.com/v1/compose/mix \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"source":{"asset_id":"ast_...","asset_token":"atok_..."},"voice":{"asset_id":"ast_...","asset_token":"atok_..."}},"options":{"mode":"duck"}}' Dubbing
Dubbing has its own guide with every status, error and the money rules: Dubbing. In short:
| Endpoint | What it does | Uses |
|---|---|---|
POST /v1/dubbing | Starts a dub; returns 202 and stops at a quote. | Transcription and translation allowances (the same as calling them yourself). |
GET /v1/dubbing/:id | Status, quote, translated lines, output. | Nothing. |
POST /v1/dubbing/:id/confirm | Accepts the quote with max_balance_micros. | Dubbing minutes, then the balance up to the confirmed amount. Speech characters. |
POST /v1/dubbing/:id/cancel | Cancels before speech starts. | Nothing more. |
All four need an API key.
Voice cloning
You can clone your own voice, or a voice you have permission to use. The consent rules are the same as on the website: you record a random sentence, speech recognition checks it, and extra samples must sound like the same person. Public figures and minors are not allowed. Cloned speech is made by Fish Audio and charged at its real cost of 15 micro-dollars per byte of text (about $0.015 per 1,000 English characters), from the daily cloned-voice allowance, not from the balance. Cloned voices speak 17 languages.
POST /v1/voices/consent-challenge
- Auth
- API key
- Uses
- Nothing.
Body {"language": "en"} or "es". Returns challenge_id, the sentence to read and expires_at (15 minutes). Each challenge works once.
curl -X POST https://api.soundhalo.com/v1/voices/consent-challenge \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"language":"en"}' POST /v1/voices
- Auth
- API key
- Uses
- Transcription for the consent check, and processing jobs to clean each recording.
Record yourself reading the whole sentence, upload the recording with POST /v1/assets, then send:
curl -X POST https://api.soundhalo.com/v1/voices \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"challenge_id":"vch_...","consent_recording":{"asset_id":"ast_...","asset_token":"atok_..."},"samples":[],"attestation":{"own_voice_or_permission":true,"not_public_figure":true,"adult":true}}' samples: up to 3 extra recordings of the same voice. Each must score at least 0.65 for sounding like the consent recording and fit in a 45-second reference, or it is left out (the response says why).attestation: all three statements must betrue.- 201 returns the voice. 422
consent_mismatchmeans the recording did not match the sentence; get a new sentence and record again. 409 means you already have a voice (delete it first) or one is being created.
Then use "voice": "personal" with "language" in text to speech, voice-over and dubbing.
GET /v1/voices/me
- Auth
- API key
- Uses
- Nothing.
Returns {"voice": {...}} or {"voice": null}.
DELETE /v1/voices/me
- Auth
- API key
- Uses
- Nothing.
Deletes your voice. The consent recording is kept for about 30 days as evidence of permission, then removed.
Lip-sync
Lip-sync changes a speaker's mouth to match a new audio track. It works on real human faces only (not animated or computer-generated faces), and only on faces you have the right to change. Jobs run on fal. Standard is included in some plans; beyond that, and for Pro and Studio quality, it is paid from the balance.
POST /v1/compose/lip-sync/quote
- Auth
- API key
- Uses
- Nothing. It measures both files; nothing is reserved.
options.quality: standard (default), pro or studio. The audio may not be more than 1 second longer than the video.
curl -X POST https://api.soundhalo.com/v1/compose/lip-sync/quote \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"video":{"asset_id":"ast_6e64b0faaeaf86bbbce16fc2fe6fdea5","asset_token":"atok_REDACTED"},"audio":{"asset_id":"ast_98f2af6078e0893308de760363107e46","asset_token":"atok_REDACTED"}},"options":{"quality":"standard"}}' The result has duration_sec, billable_seconds (Standard counts at least 40 seconds), max_duration_sec, included_seconds (plan minutes used), credit_micros (what the balance would pay), credits_per_minute (the rate in dollars), included_remaining_seconds, credit_balance_micros (your balance), resets_at and allowed (whether the balance covers it).
POST /v1/compose/lip-sync
- Auth
- API key
- Uses
- Included Standard minutes first, then the balance up to max_credit_micros.
Same input as the quote, plus options.rights_confirmed: true and options.max_credit_micros: the most the balance may pay, taken from the quote's credit_micros. If the job needs more than that, it is refused with 400 and nothing starts. Not enough balance returns 402 with needed_micros and balance_micros. Returns 202 with a lip_sync_id (lsj_...).
curl -X POST https://api.soundhalo.com/v1/compose/lip-sync \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"video":{"asset_id":"ast_...","asset_token":"atok_..."},"audio":{"asset_id":"ast_...","asset_token":"atok_..."}},"options":{"quality":"standard","rights_confirmed":true,"max_credit_micros":0}}' Only a job that fal never accepted is given back. A job fal accepted stays charged even if it later fails, and nothing is retried automatically.
GET /v1/compose/lip-sync/:id
- Auth
- API key
- Uses
- Nothing.
Status processing, completed (with output_asset, an MP4) or failed (with error). Check every 10 to 30 seconds; a job can take several minutes. The website then lays the full sound (music included) back over the lip-synced picture at full audio quality with POST /v1/compose/mix, mode replace. You can do the same.
Error codes
Errors look like { request_id, error: { code, message, details, retryable } }. The message is written for people and is safe to show to your users.
| Status | Common codes | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR, PAYMENT_REQUIRED | Something in the request is wrong, or a confirmed amount is too small. Nothing was charged. |
| 401 | AUTH_REQUIRED | Missing, wrong or revoked key. |
| 402 | PAYMENT_REQUIRED | Lip-sync: the balance is too low. Nothing started. |
| 403 | FORBIDDEN, ASSET_TOKEN_INVALID | Not allowed with a key, or a wrong file or job token. |
| 404 | NOT_FOUND | No such item for this account. |
| 409 | IDEMPOTENCY_CONFLICT | Already done or in the wrong state (for example a repeated request_id). |
| 410 | VALIDATION_ERROR | A dub quote expired after 24 hours. |
| 413 | FILE_TOO_LONG, TEXT_TOO_LONG | Over the plan's per-file or per-request limit. details gives the limit. |
| 429 | QUOTA_EXCEEDED | A daily, monthly or rate limit was reached. Nothing was charged. Wait Retry-After seconds. |
| 503 | INTERNAL_ERROR, PROVIDER_UNAVAILABLE | Busy or temporarily down. Retry after Retry-After seconds. |