Tagata Atiina'e API
Tuufaatasia le fa'avasegaina o Addavox i lau faiga o galuega. Filifili le Fa'aliliuina o Vitio API mo le fa'avasegaina atoa o vitio fa'atasi ai ma le taimi, QA, ulutala, ma le avanoa atoa i le Iloiloga Faatonu e ala i so'otaga fa'ataulaitu. E mafai foi ona e filifilia so'o se tasi o API tautua mo isi galuega, e pei o le fa'amatalaina o se tusi po'o le fa'aliliuina ma le fa'amatalaina o se tusi i le taimi e tasi.
Ki API
O ki API e patino i se teugatupe Addavox. Fausia se tasi i le fa'amau Amata le fa'avasegaina i luga, ona faia lea o se ki i totonu o le app — o vala'au uma e totogi i lena teugatupe. Ina ia fausia ma fa'ata'ita'i se feso'ota'iga muamua, talosaga mo se ki sandbox i totonu o le app.
O auaunaga ta'ito'atasi API e totogi mai lau paleni aitalafu, lea e te fa'atumu ma pulea i lau teugatupe Addavox . O le tuusaunoaga o le vitio atoa o le fa'asalalauga: e fa'aogaina le tau tutusa e pei o le fuafuaga e te filifilia i Fuafuaga & Tau — o minute o lau fuafuaga e aofia ai, ona ova lea i le fua faatatau o le fuafuaga.
Fuafuaina se tu'ufa'atasiga? Fa'atulaga se vala'au fa'atasi (tatala i se tab fou)
URL Autu:
https://api.addavox.com/api/v1
Ulutala Fa'amaonia:
X- API -Ki: LAU_KI
Maliega ma le Fa'atagaga
E tatau ona aofia i talosaga uma API se mea e fai ai le maliega ma se fanua e fai ai le tulaga pito i luga. O nei mea uma e fausia ai se faamaumauga faamaonia mo galuega taitasi e faamaonia ai o loo ia te oe aia tatau talafeagai ma maliega a le failauga.
O le fanua o le mode e fuafua ai le tuufaatasiga o leo: "voice_matched" e faʻaaogaina fa'afetauiga o Leo, lea e tauaveina ai le leo ma lagona o failauga taʻitasi i le gagana faʻamoemoeina; "standard" e faʻaaogaina leo faʻapitoa ua uma ona setiina. E tutusa le tau o mode uma e lua — o le filifiliga e faʻavae i le maliega.
Faiga Fa'afetaui Leo — Mana'omia le Maliega Atoatoa
Faiga Masani — Aia Tatau i Mataupu
Fa'asinomaga i le Fanua
| Fanua | Ituaiga | Mana'omia | Fa'amatalaga |
|---|---|---|---|
| mode | string | Tulaga maualuga | voice_matched pe standard |
| speaker_consent_obtained | boolean | na'o le leo_matched | Maliega manino mai failauga e mafai ona iloa |
| content_rights_confirmed | boolean | Faiga uma e lua | Puleaina po'o le laisene aloaia i le anotusi |
| eula_accepted | boolean | Faiga uma e lua | Taliaina le Addavox EULA |
| attested_by | string | Faiga uma e lua | Imeli po'o le fa'ailoaina o le vaega e nafa ma le matafaioi |
| attested_at | ISO 8601 | Faiga uma e lua | I totonu ole 24 itula talu ona talosagaina |
Fa'ailoga Sese o le Maliega
| HTTP | Tulafono | Tulaga |
|---|---|---|
| 403 | CONSENT_MISSING | Leai se maliega |
| 403 | CONSENT_INCOMPLETE | Ua misi le attested_by pe le aoga le attested_at |
| 403 | CONSENT_NOT_AFFIRMED | E le'i fa'amaonia aia tatau po'o EULA |
| 403 | CONSENT_EXPIRED | ua faamaonia_pe a sili atu i le 24 itula |
| 403 | SPEAKER_CONSENT_REQUIRED | leo_tutusa e aunoa ma le maliega a le failauga |
| 400 | INVALID_MODE | Tau fa'aoga le aoga |
API Fa'asinomaga
O lo'o maua le fa'atulagaga atoa o fegalegaleaiga ma isi fa'ai'uga fa'aopoopo e ala i le OpenAPI.
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' (voice matching: each speaker's tone and emotion carried into the target language); 'standard' uses preset synthetic voices. |
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 an audio sample you provide. There is no minimum length; samples of about 3–5 seconds or more work best. 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. |
Tau o Auaunaga API
E totogi auaunaga ta'itasi i le minute ma e le o se vaega o se fuafuaga — e te totogia na'o le mea e te vala'au i ai, i le fua fa'atatau e tasi e aunoa ma se fa'aitiitiga fa'aletausaga. E na'o le fa'asalalauga atoa o vitio e fa'avae i luga o minute o lo'o aofia i le fuafuaga. E tusa ma le 1,000 mata'itusi i le minute le aofa'i o auaunaga fa'avae i tusitusiga.
| Auaunaga | O le mea e te auina atu → o le mea e te mauaina | Fua faatatau |
|---|---|---|
| Vavaeeseina o Leo | Leo → leo mamā + pese i tua | $0.02/min |
| Fa'aliliuga (STT) | Leo → tusitusiga o le tusitusiga ma fa'ailoga ma le taimi e tusa ai ma upu | $0.02/min |
| Fa'aliliuga Pro | Leo → Vavaeeseina o Leo + Fa'aliliuga (STT), sili ona lelei mo leo pisapisao | $0.05/min |
| Faaliliuga | Tusitusiga → tusitusiga ua faaliliuina | $0.02/min |
| Fa'amatala (TTS) | Tusitusiga fa'aliliu → leo fa'amatala i se leo ua uma ona setiina e te filifilia | $0.03/min |
| Faaliliu + Faamatala — leo ua uma ona setiina | Tusitusiga → ua faaliliuina, ona faamatala lea i se leo ua uma ona faatulagaina. E tatau ona eseese le gagana na amata mai ai ma le gagana e faatatau i ai. | $0.06/min |
| Faaliliu + Faamatala — leo fetaui | Tusitusiga + se faʻataʻitaʻiga o le leo (leai se umi maualalo; 3–5 sekone pe sili atu e sili ona lelei) → faʻaliliuina, ona faʻamatala lea i le leo e fetaui. E tatau ona eseese le gagana na faʻaaogaina ma le gagana e faʻaaogaina. | $0.08/min |
O le fa'avasegaina atoa o vitio o le tautua API e feso'ota'i ma se fuafuaga: e fa'aaoga i minute o lau fuafuaga ua aofia ai, ona ova lea i le fua faatatau o le fuafuaga. Va'ai fuafuaga ma tau