Developer API
Addavox naannoo adeemsa hojii kee keessatti walitti makuu. Viidiyoo Dubbing API filadhu, yeroo, QA, mata duree xiqqaa, fi qaqqabummaa guutuu Gulaalaa Irra Deebi'uu karaa hidhaa falfalaatiin. Akkasumas hojiiwwan biroof API tajaajila dhuunfaa kamiyyuu filachuu dandeessa, kan akka kitaaba seenessuu ykn kitaaba tokko dabarsuu tokkoon hiikuu fi seenessu.
API Furtuuwwan
Furtuuwwan API kan herrega Addavox ti. Tokko button Start localizing armaan olitti uumi, sana booda furtuu app keessatti uumi — bilbilli hundi herrega sanaaf kaffaltii.
Tajaajilli dhuunfaa API kan kaffalamu hafnaan liqii keessan irraa yoo ta’u, kanas herrega Addavox keessan keessatti guuttanii bulchitan. Viidiyoo guutuu naannootti jijjiiruun ala: gatii karoora ati Karoora fi Gatii keessatti filatte fayyadama — daqiiqaawwan karoorri kee hammataman, sana booda saffisa karooraatiin olka’iinsa.
URL bu'uuraa:
https://api.addavox.com/api/v1
Mataduree Auth:
X- API -Furtuu: FURTUU_KEE
Hayyama fi Hayyama
Gaaffiiwwan API hundi wanta hayyamaa fi dirree haalata sadarkaa ol'aanaa of keessatti qabachuu qabu. Isaan kun waliin ta’uun galmee ragaa hojii tokkoof mirga barbaachisaa fi hayyama dubbataa qabaachuu kee mirkaneessu uumu.
Dirreen haalaa walnyaatinsa sagalee murteessa: "voice_matched" sagalee sagalee guddiftuu kloonii fayyadama, "standard" TTS sinteetikii fayyadama. Haalli lamaan gatii walfakkaataadha — filannoo hayyama qofaan kan hoogganamudha.
Haala Sagalee Walsimsiisu — Hayyama Guutuu Barbaachisa
Haalata Istaandardii — Mirga Qabiyyee Qofa
Wabii Dirree
| Dirree | Akaakuu | Kan barbaadamu | Ibsa |
|---|---|---|---|
| mode | string | Sadarkaa olaanaa | voice_matched yookaan standard |
| speaker_consent_obtained | boolean | sagalee_walsimsiisu qofa | Hayyama ifa ta’e dubbattoota adda baafamuu danda’an irraa |
| content_rights_confirmed | boolean | Haala lamaan | Qabiyyee sanaaf abbummaa ykn hayyama seera qabeessa ta’e |
| eula_accepted | boolean | Haala lamaan | Addavox EULA fudhata |
| attested_by | string | Haala lamaan | Imeelii ykn adda baastuu qaama itti gaafatamummaa qabu |
| attested_at | ISO 8601 | Haala lamaan | Yeroo gaaffii sa'aatii 24 keessatti |
Koodiiwwan Dogoggora Hayyama
| HTTP | Koodii | Haala |
|---|---|---|
| 403 | CONSENT_MISSING | Mormii hayyamaa hin qabu |
| 403 | CONSENT_INCOMPLETE | Attested_by dhabame ykn attested_at sirrii hin taane |
| 403 | CONSENT_NOT_AFFIRMED | Mirgoonni ykn EULA hin mirkanoofne |
| 403 | CONSENT_EXPIRED | attested_at sa'aatii 24 ol ta'e |
| 403 | SPEAKER_CONSENT_REQUIRED | sagalee_walsimsiise hayyama dubbataa malee |
| 400 | INVALID_MODE | Gatii haalata sirrii hin taane |
API Wabii
Iskiimaa walqunnamtii guutuu fi qabxiiwwan xumuraa dabalataa karaa Banaa API ni argamu.
Full Video Localization
/api/v1/localize-video
API key
Video Dubbing
Full video dubbing: send a video URL + target languages, get localized videos back.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
video_url |
string |
Yes | HTTPS URL of the source video to dub. |
target_languages |
string[] |
Yes | One or more target language codes. |
source_language |
string |
Yes | Language of the source video's spoken audio, e.g. 'en'. |
project_name |
string | null |
No | Optional project name. Defaults to 'API Video: {filename}'. |
enable_llm_qa |
boolean |
No | Opt-in LLM quality-review pass over translations before voice synthesis. Adds processing time. |
mode |
LocalizationMode |
No | Drives consent. Default 'voice_matched' (clones the speaker); 'standard' uses synthetic TTS. |
consent |
ConsentAttestation |
Yes | Consent attestation; see Consent & Authorization. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Master job ID — poll for per-language status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
target_languages |
string[] |
Echoed target language codes. |
ConsentAttestation
speaker_consent_obtained |
boolean | null |
Attests that explicit consent has been obtained from all identifiable speakers. Required for voice_matched mode only. |
content_rights_confirmed |
boolean |
Attests ownership or a valid license to the content. Required in both modes. |
eula_accepted |
boolean |
Confirms the client has read and accepts the Addavox EULA. Required in both modes. |
attested_by |
string |
Email or identifier of the responsible individual or system. |
attested_at |
string |
ISO 8601 timestamp of attestation. Must be within 24 hours of the request. |
API Services
/api/v1/separate
API key
Voice Separation
Split caller-supplied audio into vocals + background stems (async job).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio to separate. |
project_name |
string | null |
No | Optional project name. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
charge |
ChargeInfo |
Billing detail for this submission. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
/api/v1/transcribe
API key
Transcribe
Transcribe caller-supplied audio and return a transcript (async job).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio to transcribe. |
language |
string |
Yes | Spoken language of the audio (BCP-47), e.g. 'en-US'. |
project_name |
string | null |
No | Optional project name. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
charge |
ChargeInfo |
Billing detail for this submission. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
/api/v1/pro-transcribe
API key
Pro Transcription
Separate, then transcribe the isolated vocals stem — a cleaner transcript (async job).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio to transcribe. |
language |
string |
Yes | Spoken language of the audio (BCP-47), e.g. 'en-US'. |
project_name |
string | null |
No | Optional project name. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
charge |
ChargeInfo |
Billing detail for this submission. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
/api/v1/translate
API key
Translate
Machine-translate text from one language to another. Returns the translated text synchronously — no audio, no job to poll.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
text |
string |
Yes | Text to translate. |
target_language |
string |
Yes | Target language code, e.g. 'es' or 'es-ES'. |
source_language |
string |
Yes | Source language code, e.g. 'en' or 'en-US'. |
Response
| Field | Type | Description |
|---|---|---|
translated_text |
string |
The translated text. |
source_language |
string |
Source language supplied on the request. |
target_language |
string |
Target language the text was translated into. |
charge |
ChargeInfo |
Billing detail for this translation. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
Example
curl -X POST https://api.addavox.com/api/v1/translate \
-H "X-API-Key: $ADDAVOX_KEY" -H "Content-Type: application/json" \
-d '{"text": "Hello", "target_language": "es"}'
/api/v1/narrate
API key
Narrate
Narrate already-translated text into an audiobook, in a preset voice you choose. Preset (synth) voices only — no voice matching.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio; also used to identify/match speaker voices. |
source_language |
string |
Yes | Source language code, e.g. 'en-US'. |
target_language |
string |
Yes | Target language code, e.g. 'es-ES'. |
segments |
ExternalSegment[] |
Yes | The pre-segmented transcript to voice. |
project_name |
string | null |
No | Optional project name. Defaults to 'API: {source}->{target}'. |
consent |
ConsentAttestation |
Yes | Consent attestation; see Consent & Authorization. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
voice_type |
string |
Voice type resolved from the request mode. |
total_segments |
integer |
Echoed count of submitted segments. |
charge |
ChargeInfo |
Billing detail for this submission. |
ExternalSegment
source_text |
string |
Original text for this segment. |
start_time |
number |
Segment start, in seconds. Used for speaker-voice matching only, not output timing. |
end_time |
number |
Segment end, in seconds. Used for speaker-voice matching only, not output timing. |
words |
object[] |
Word-level timing; defaults to empty. |
speaker |
object | null |
Speaker metadata for voice selection. |
translated_text |
string | null |
Pre-supplied translation. If provided, translation is skipped for this segment. |
ConsentAttestation
speaker_consent_obtained |
boolean | null |
Attests that explicit consent has been obtained from all identifiable speakers. Required for voice_matched mode only. |
content_rights_confirmed |
boolean |
Attests ownership or a valid license to the content. Required in both modes. |
eula_accepted |
boolean |
Confirms the client has read and accepts the Addavox EULA. Required in both modes. |
attested_by |
string |
Email or identifier of the responsible individual or system. |
attested_at |
string |
ISO 8601 timestamp of attestation. Must be within 24 hours of the request. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
/api/v1/translate-narrate
API key
Translate + Narrate — preset voice
Translate your text to the target language and narrate it in a preset voice. Source and target language must differ.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio; also used to identify/match speaker voices. |
source_language |
string |
Yes | Source language code, e.g. 'en-US'. |
target_language |
string |
Yes | Target language code, e.g. 'es-ES'. |
segments |
ExternalSegment[] |
Yes | The pre-segmented transcript to voice. |
project_name |
string | null |
No | Optional project name. Defaults to 'API: {source}->{target}'. |
consent |
ConsentAttestation |
Yes | Consent attestation; see Consent & Authorization. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
voice_type |
string |
Voice type resolved from the request mode. |
total_segments |
integer |
Echoed count of submitted segments. |
charge |
ChargeInfo |
Billing detail for this submission. |
ExternalSegment
source_text |
string |
Original text for this segment. |
start_time |
number |
Segment start, in seconds. Used for speaker-voice matching only, not output timing. |
end_time |
number |
Segment end, in seconds. Used for speaker-voice matching only, not output timing. |
words |
object[] |
Word-level timing; defaults to empty. |
speaker |
object | null |
Speaker metadata for voice selection. |
translated_text |
string | null |
Pre-supplied translation. If provided, translation is skipped for this segment. |
ConsentAttestation
speaker_consent_obtained |
boolean | null |
Attests that explicit consent has been obtained from all identifiable speakers. Required for voice_matched mode only. |
content_rights_confirmed |
boolean |
Attests ownership or a valid license to the content. Required in both modes. |
eula_accepted |
boolean |
Confirms the client has read and accepts the Addavox EULA. Required in both modes. |
attested_by |
string |
Email or identifier of the responsible individual or system. |
attested_at |
string |
ISO 8601 timestamp of attestation. Must be within 24 hours of the request. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
/api/v1/translate-narrate-matched
API key
Translate + Narrate — matched voice
Translate your text to the target language and narrate it in a voice matched from a ≥1-minute audio sample you provide. Source and target language must differ.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string |
Yes | HTTPS URL of the source audio; also used to identify/match speaker voices. |
source_language |
string |
Yes | Source language code, e.g. 'en-US'. |
target_language |
string |
Yes | Target language code, e.g. 'es-ES'. |
segments |
ExternalSegment[] |
Yes | The pre-segmented transcript to voice. |
project_name |
string | null |
No | Optional project name. Defaults to 'API: {source}->{target}'. |
consent |
ConsentAttestation |
Yes | Consent attestation; see Consent & Authorization. |
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Poll this job ID for status. |
project_id |
string |
The project created for this job. |
status |
string |
Always 'queued' on submit. |
voice_type |
string |
Voice type resolved from the request mode. |
total_segments |
integer |
Echoed count of submitted segments. |
charge |
ChargeInfo |
Billing detail for this submission. |
ExternalSegment
source_text |
string |
Original text for this segment. |
start_time |
number |
Segment start, in seconds. Used for speaker-voice matching only, not output timing. |
end_time |
number |
Segment end, in seconds. Used for speaker-voice matching only, not output timing. |
words |
object[] |
Word-level timing; defaults to empty. |
speaker |
object | null |
Speaker metadata for voice selection. |
translated_text |
string | null |
Pre-supplied translation. If provided, translation is skipped for this segment. |
ConsentAttestation
speaker_consent_obtained |
boolean | null |
Attests that explicit consent has been obtained from all identifiable speakers. Required for voice_matched mode only. |
content_rights_confirmed |
boolean |
Attests ownership or a valid license to the content. Required in both modes. |
eula_accepted |
boolean |
Confirms the client has read and accepts the Addavox EULA. Required in both modes. |
attested_by |
string |
Email or identifier of the responsible individual or system. |
attested_at |
string |
ISO 8601 timestamp of attestation. Must be within 24 hours of the request. |
ChargeInfo
amount |
number |
Total amount charged for this submission, in USD. |
rate_per_min |
number |
Per-minute rate applied. |
duration_min |
number |
Billed minutes (for text services, characters/1000). |
num_languages |
integer |
Number of target languages billed. |
credit_balance_after |
number |
Account credit balance after the charge, in USD. |
Jobs & Results
/api/v1/jobs/{job_id}
API key
Job Status
Check the status of an external localization job.
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Echoes the job ID from the URL. |
type |
string |
Job type: voice | translate_voice | transcribe_translate_voice | video_dub. |
status |
string |
queued | running | completed | failed. For a video_dub job this is a true aggregate of its per-language children, not a per-child value. |
total_segments |
integer |
Total segment count. Always 0 on a video_dub master job. |
completed_segments |
integer |
Completed segment count. Always 0 on a video_dub master job. |
error |
string | null |
Failure message when status is 'failed'. |
/api/v1/jobs/{job_id}/result
API key
Job Result
Get the download URL for a completed external localization job.
Response
| Field | Type | Description |
|---|---|---|
transcript_url |
string | null |
(Transcription job) Signed URL of the transcript JSON. |
vocals_url |
string | null |
(Separation job) Signed URL of the vocals stem. |
background_url |
string | null |
(Separation job) Signed URL of the background stem. |
download_url |
string | null |
Signed URL (24h). Single voice track for an audio job, or a zip of all languages for a video dub. |
duration |
number | null |
(Audio job) Duration in seconds. |
file_size |
integer | null |
(Audio job) File size in bytes. |
project_id |
string | null |
(Video dub) The project ID. |
review_url |
string | null |
(Video dub) Web review URL for the project. |
languages |
VideoJobResultLanguage[] | null |
(Video dub) Per-language result URLs. |
VideoJobResultLanguage
language |
string |
Target language code for this result. |
video_url |
string | null |
Signed URL of the dubbed video (24h expiry). |
audio_url |
string | null |
Signed URL of the dubbed audio track (24h expiry). |
subtitle_url |
string | null |
Signed URL of the subtitle file (24h expiry). |
/api/v1/jobs/{job_id}
API key
Cancel Job
Cancel a queued or running job and refund the charge to the account balance.
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Echoes the cancelled job ID. |
status |
string |
Always 'cancelled'. |
refunded_amount |
number |
Amount refunded for the undelivered work, in USD. |
/api/v1/jobs
API key
List Jobs
List localization jobs for the authenticated account. Query params: status — filter by queued | running | completed | failed | cancelled limit — max results (default 20, max 100) offset — pagination offset (default 0)
Response
| Field | Type | Description |
|---|---|---|
jobs |
JobListItem[] |
The page of jobs, newest first. |
total |
integer |
Total jobs matching the query, across all pages. |
limit |
integer |
Page size used. |
offset |
integer |
Page offset used. |
JobListItem
job_id |
string |
Job ID. |
project_id |
string |
Project the job belongs to. |
type |
string |
Job type. |
target_language |
string | null |
Target language code, if applicable. |
status |
string |
queued | running | completed | failed | cancelled. |
total_segments |
integer |
Total segment count. |
completed_segments |
integer |
Completed segment count. |
error |
string | null |
Failure message when the job failed. |
created_at |
string | null |
ISO 8601 creation time. |
started_at |
string | null |
ISO 8601 start time, if started. |
completed_at |
string | null |
ISO 8601 completion time, if finished. |
charge |
JobListCharge | null |
Charge summary, present if the job was billed. |
/api/v1/jobs/{job_id}/webhooks
API key
Webhook Log
Return the webhook delivery log for a job (all attempts, newest first).
Response
| Field | Type | Description |
|---|---|---|
job_id |
string |
Echoes the job ID from the URL. |
deliveries |
WebhookDelivery[] |
All delivery attempts for the job, newest first. |
WebhookDelivery
id |
string | null |
Delivery attempt ID. |
event |
string | null |
Event type delivered, e.g. 'job.completed'. |
attempt |
integer | null |
Attempt number for this event. |
status_code |
integer | null |
HTTP status returned by the endpoint, if any. |
error |
string | null |
Delivery error, if the attempt failed. |
delivered_at |
string | null |
ISO 8601 time of the attempt. |
/api/v1/jobs/{job_id}/webhooks/retry
API key
Retry Webhook
Re-trigger webhook delivery for the most recent event on a job.
Response
| Field | Type | Description |
|---|---|---|
status |
string |
Always 'queued' — the event was re-queued for delivery. |
event |
string |
The event type that was re-queued. |
Account & Reference
/api/v1/account
API key
Account
Return credit balance and current plan for the authenticated account.
Response
| Field | Type | Description |
|---|---|---|
account_id |
string |
The account's ID. |
credit_balance |
number |
Prepaid credit balance, in USD. |
plan_id |
string |
Current plan ID, e.g. 'free', 'creator'. |
plan_name |
string |
Human-readable plan name. |
included_minutes |
integer |
Localization minutes included in the plan per period. |
minutes_used |
number |
Included minutes used this period. |
minutes_remaining |
number |
Included minutes remaining this period. |
overage_rate |
number |
Per-minute overage rate once included minutes are exhausted, in USD. |
billing_interval |
string | null |
'monthly' or 'annual'; null on the free plan. |
subscription_status |
string |
Subscription status, e.g. 'active', 'past_due', 'free'. |
/api/v1/voices
API key
List Voices
Return available voices for a given language code. Query params: language — BCP-47 code, e.g. 'en-US', 'es-ES' (required) gender — optional filter: MALE | FEMALE
/api/v1/languages
API key
List Languages
Return supported languages. Query params: detail — if true, include provider metadata per language
/api/v1/projects/{project_id}/reviewers
API key
Invite Reviewer
Invite a reviewer to a project (API endpoint).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Reviewer's display name, used in the invite email. |
email |
string |
Yes | Where the magic-link invite is sent. |
language |
string |
Yes | Target language code the reviewer will edit. |
Response
| Field | Type | Description |
|---|---|---|
id |
string |
New reviewer ID. |
name |
string |
Echoed from the request. |
email |
string |
Echoed from the request. |
token |
string |
Magic-link token, embedded in the emailed URL. Expires 7 days from creation. |
expires_at |
string | null |
Currently always null — not populated by this call. |
API Gatii Tajaajilaa
Tajaajilli dhuunfaa daqiiqaa tokkoof kaffaltiin kan kaffalamu yoo ta’u qaama karooraa miti — waan bilbiltu qofaaf kaffalta, gatii walfakkaatu tokkoon hir’ina waggaa tokko malee. Viidiyoo guutuu localization qofti daqiiqaawwan karoora tokko keessatti hammataman irraa fudhata. Tajaajiloonni barreeffama irratti hundaa'an daqiiqaa tokkotti tilmaamaan arfiilee 1,000n meetira.
| Tajaajila | Waan ergitu → waan argattu | Gatii |
|---|---|---|
| Sagalee Addaan Bahuu | Sagalee → sagalee qulqulluu + track duubaa | $0.02/min |
| Tiraanskriipshinii (STT) . | Sagalee → barreeffama barreeffamaa mallattoolee addaan kutuu fi yeroo sadarkaa jechaa wajjin | $0.02/min |
| Pro Transcription jedhu | Sagalee → Sagalee Addaan Baasuun + Tiraanskriipshinii (STT), sagalee sagalee guddaa qabuuf gaarii dha | $0.05/min |
| Hiikaa | Barreeffama → barreeffama hiikame | $0.02/min |
| Seenessuu (TTS) 1.1. | Barreeffama → sagalee dursee murtaa’een seeneffame | $0.03/min |
| Hiikkaa + Seenessuu — sagalee dursee murtaa’e | Barreeffama → hiikame, sana booda sagalee dursee murtaa’een kan seeneffame | $0.06/min |
| Hiikkaa + Seenessuu — sagalee walsimsiisu | Barreeffama + saamuda sagalee ≥1-min → hiikame, sana booda sagalee walsimsiifameen seeneffama. Afaan maddaafi xiyyeeffannoo garaagarummaa qabaachuu qaba. | $0.08/min |
Guutuu viidiyoo naannootti galchuu tajaajila API karoora tokkotti hidhameedha: daqiiqaawwan karoora kee hammataman irraa fudhata, sana booda saffisa karooraatiin olka'iinsa. Karoora fi gatii ilaali