Developer docs

API reference

Each endpoint below lists who can call it, what it uses from your plan or balance, and a real example. The full machine-readable description is the OpenAPI document.

Conventions

  • Base URL https://api.soundhalo.com. OpenAPI 3.1: /v1/openapi.json.
  • Examples use $SOUNDHALO_API_KEY for your key. Real tokens and request ids in the examples are replaced with atok_REDACTED, jtok_REDACTED and req_REDACTED.
  • Responses use the envelope { request_id, status, operation, result, job, receipt, warnings }. Read warnings: 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.

request
curl https://api.soundhalo.com/v1/assets \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY" \
  -F "file=@interview.mp3"
201 response (shape)
{
  "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):

429 QUOTA_EXCEEDED
{
  "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.

request
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.

request
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).

request
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, creator or business.
  • 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 called credits for 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_percent of the plan's monthly cost cap.
request
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:

request
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"}}'
202 response
{
  "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.

request
curl https://api.soundhalo.com/v1/jobs/job_7dbceef5aca5b6b27848e719a18a8f69 \
  -H "Authorization: Bearer $SOUNDHALO_API_KEY" \
  -H "x-job-token: jtok_REDACTED"
response
{
  "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.

request
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"}}'
response
{
  "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.

request
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.

request
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"}}'
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": []
}

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.

request
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"}}'
response
{
  "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.

request
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:

EndpointWhat it doesUses
POST /v1/dubbingStarts a dub; returns 202 and stops at a quote.Transcription and translation allowances (the same as calling them yourself).
GET /v1/dubbing/:idStatus, quote, translated lines, output.Nothing.
POST /v1/dubbing/:id/confirmAccepts the quote with max_balance_micros.Dubbing minutes, then the balance up to the confirmed amount. Speech characters.
POST /v1/dubbing/:id/cancelCancels 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.

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.

request
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:

request
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 be true.
  • 201 returns the voice. 422 consent_mismatch means 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.

request
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_...).

request
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.

StatusCommon codesMeaning
400VALIDATION_ERROR, PAYMENT_REQUIREDSomething in the request is wrong, or a confirmed amount is too small. Nothing was charged.
401AUTH_REQUIREDMissing, wrong or revoked key.
402PAYMENT_REQUIREDLip-sync: the balance is too low. Nothing started.
403FORBIDDEN, ASSET_TOKEN_INVALIDNot allowed with a key, or a wrong file or job token.
404NOT_FOUNDNo such item for this account.
409IDEMPOTENCY_CONFLICTAlready done or in the wrong state (for example a repeated request_id).
410VALIDATION_ERRORA dub quote expired after 24 hours.
413FILE_TOO_LONG, TEXT_TOO_LONGOver the plan's per-file or per-request limit. details gives the limit.
429QUOTA_EXCEEDEDA daily, monthly or rate limit was reached. Nothing was charged. Wait Retry-After seconds.
503INTERNAL_ERROR, PROVIDER_UNAVAILABLEBusy or temporarily down. Retry after Retry-After seconds.