Developer docs

SoundHalo API

Dub, voice, translate and transcribe audio and video from your own code or from an AI assistant. An API key acts as your account, so it uses the same plan minutes, balance and limits as the website tools.

What the API does

  • Dubbing: send a recording or video, get it back in another language. It stops at a quote, and nothing is spoken or paid until you confirm. Dubbing guide.
  • Transcription: speech to text with timestamps, right away or as a job you check later.
  • Caption translation: translate timed lines and keep their times and order.
  • Text to speech: 92 voices in 26 languages, MP3 or WAV.
  • Voice-over and mix: turn timed lines into one voice track, then lay it over a video or recording.
  • Voice cloning: your own voice, after a recorded consent sentence. Lip-sync: match a speaker's mouth to new audio.
  • Webhooks: signed events when a job finishes or a dub is ready to confirm. Webhooks.
  • MCP server: connect Claude, ChatGPT or another AI app so it can dub and voice files for you. MCP (Model Context Protocol) is the standard way AI apps call outside tools. MCP setup.

Basics

Base URLhttps://api.soundhalo.com
Staginghttps://api-staging.soundhalo.com, with its own sh_test_ keys. Staging calls real providers too.
AuthAuthorization: Bearer sh_live_.... See Authentication.
FormatJSON in, JSON out. File uploads use multipart/form-data.
MoneyAmounts are micro-dollars: 1,000,000 = $1, so 250000 is $0.25.
OpenAPIGET /v1/openapi.json (OpenAPI 3.1, for code generators and API tools)

Every answer uses the same envelope. Successful calls look like { request_id, status, operation, result, job, receipt, warnings }. Errors look like { request_id, error: { code, message, details, retryable } }, and a 429 or 503 also sends a Retry-After header with the seconds to wait.

Quick start

1. Create a key

Sign in and open soundhalo.com/app/#/developers. Name the key and copy it. It is shown once. Keep it on your server, never in a web page or app that other people can open.

shell
export SOUNDHALO_API_KEY="sh_live_..."

2. Check what you have left

usage
curl https://api.soundhalo.com/v1/usage/processing \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY"

The result shows your plan, dubbing.remaining_seconds this month, today's allowances (speech, synthesis, clone, transform), monthly.remaining_percent of your monthly cost cap and your prepaid balance in credits.balance_micros. Reading it costs nothing.

3. Turn text into speech

Pick a voice from GET /v1/generate/speech/voices (no key needed), then:

text to speech
curl 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"}}'
response
{
  "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": []
}

This used 127 of today's text to speech characters. It never uses your balance. Download the file with its asset token:

download
curl -o speech.mp3 \
  -H "x-asset-token: atok_REDACTED" \
  https://api.soundhalo.com/v1/assets/ast_6e64b0faaeaf86bbbce16fc2fe6fdea5/download

Your first dub

A dub has two halves. First SoundHalo transcribes and translates your file and gives you a quote. Then you confirm the quote, and only then is anything spoken or paid from your balance.

1. Upload the file

upload
curl https://api.soundhalo.com/v1/assets \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY" \
  -F "file=@interview.mp3"

Keep result.asset_ref (an asset_id and an asset_token). Uploads count toward a daily limit (3 files a day on Free; see Limits).

2. Start the dub

start a dub
curl https://api.soundhalo.com/v1/dubbing \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"asset_ref":{"asset_id":"ast_...","asset_token":"atok_..."}},"options":{"voice":"es-dora","format":"mp3"}}'

You get 202 and a dub_id with status transcribing. The voice sets the language: es-dora speaks Spanish.

3. Wait for the quote

check the dub
curl https://api.soundhalo.com/v1/dubbing/dub_a550d99c9a0ba49ec77094a7de4fc0c9 \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY"

Check every 10 seconds or so, or use the dub.awaiting_confirmation webhook. When status is awaiting_confirmation, the dub has the translated lines and a quote. This is the quote for a real 9-second recording on an account with no dubbing minutes left:

result.dub.quote
{
  "billable_seconds": 10,
  "by_text": false,
  "plan_seconds": 0,
  "plan_seconds_left": 0,
  "balance_micros": 41667,
  "balance_available_micros": 19874999,
  "lines": 3,
  "lines_total": 3
}

The last line ends at 9.86 seconds, so the dub counts 10 seconds. None come from the plan, so the balance would pay 41,667 micro-dollars: 10 seconds at $0.25 a minute, about $0.04.

4. Confirm

confirm
curl https://api.soundhalo.com/v1/dubbing/dub_a550d99c9a0ba49ec77094a7de4fc0c9/confirm \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_balance_micros":41667}'

max_balance_micros is the most your balance may pay. It must be at least quote.balance_micros, and SoundHalo never takes more. The dub moves to generating, then succeeded. Its output has a download_url and an asset_token for the download header.

Without a key

The free tools and the anonymous endpoints in the getting started guide still work without an account. They share small limits per network (30 POST requests an hour per IP address). Dubbing, voice cloning, lip-sync, webhooks and the MCP server need an account.

Where to go next