Pêşdebir API
Herêmîkirina Addavox di nav herikîna karê xwe de entegre bike. Ji bo herêmîkirina tevahî ya vîdyoyê bi demjimêr, QA, jêrnivîsan, û gihîştina tevahî ya Edîtorê Nirxandinê bi rêya girêdanên sêrbaz, Dublaja Vîdyoyê API hilbijêre. Her weha hûn dikarin ji bo karên din, wekî vegotina pirtûkek an wergerandin û vegotina pirtûkek bi carekê ve, her yek ji API-yên karûbarê yên takekesî hilbijêrin.
API Kilît
Kilîtên API ên hesabê Addavox in. Bi bişkoja Destpêkirina herêmîkirinê ya li jor yek çêbikin, dûv re di sepanê de kilîtek çêbikin - her bang ji wî hesabê re tê fatûrekirin.
Xizmetên API yên ferdî ji mîqdara krediya we têne dayîn, ku hûn wê di hesabê xwe Addavox de tijî dikin û birêve dibin. Lokalîzasyona vîdyoyê ya tevahî îstîsna ye: ew heman bihayê wekî plana ku hûn di Plan & Bihayan de hildibijêrin bikar tîne - deqeyên ku di plana we de hene, dûv re jî bi rêjeya planê zêde dibe.
URL-ya bingehîn:
https://api.addavox.com/api/v1
Sernivîsa destûrnameyê:
X- API -Kilît: KILITA_YOUR
Razîbûn û Destûr
Divê hemû daxwazên API tiştekî razîbûnê û qadeke moda asta jorîn di nav xwe de bigirin. Ev bi hev re qeydeke pejirandinê ya ji bo her karî diafirînin ku piştrast dike ku mafên pêwîst û razîbûna axaftvan li cem we hene.
Qada modê senteza deng diyar dike: "voice_matched" klona dengê axaftvan bikar tîne, "standard" TTS-ya sentetîk bikar tîne. Her du mod jî bi heman bihayê ne - hilbijartin bi tevahî li ser razîbûnê ye.
Moda Deng-Hevberkirî — Razîbûna Tam Pêwîst e
Moda Standard — Tenê Mafên Naverokê
Referansa Zeviyê
| Erd | Awa | Pêwîst | Terîf |
|---|---|---|---|
| mode | string | Asta jorîn | voice_matched an standard |
| speaker_consent_obtained | boolean | tenê deng_hevberkirî | Razîbûna eşkere ji axaftvanên ku dikarin bêne naskirin |
| content_rights_confirmed | boolean | Her du mod jî | Xwedîtî an lîsansa derbasdar a naverokê |
| eula_accepted | boolean | Her du mod jî | EULA ya Addavox qebûl dike |
| attested_by | string | Her du mod jî | E-name an nasnameya aliyê berpirsiyar |
| attested_at | ISO 8601 | Her du mod jî | Di nav 24 demjimêran de piştî dema daxwazê |
Kodên Çewtiyên Razîbûnê
| HTTP | Navê dizî | Rewş |
|---|---|---|
| 403 | CONSENT_MISSING | Ne tiştek e ku razîbûnê hebe |
| 403 | CONSENT_INCOMPLETE | attested_by winda ye an jî attested_at nederbasdar e |
| 403 | CONSENT_NOT_AFFIRMED | Maf an EULA nehatine pejirandin |
| 403 | CONSENT_EXPIRED | ji 24 demjimêran kevintir hatiye piştrastkirin |
| 403 | SPEAKER_CONSENT_REQUIRED | voice_matched bêyî razîbûna axaftvan |
| 400 | INVALID_MODE | Nirxa moda nederbasdar |
API Referans
Nexşeya înteraktîf a tevahî û xalên dawî yên zêde bi rêya Open API peyda dibin.
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 Nirxandina Xizmetê
Xizmetên ferdî li gorî hûrdemê têne hesabkirin û ne beşek ji planekê ne - hûn tenê ji bo tiştê ku hûn telefon dikin didin, bi rêjeyek sabît bêyî dakêşana salane. Tenê herêmîkirina vîdyoyê ya tevahî ji hûrdemên ku di planê de hene sûd werdigire. Xizmetên li ser bingeha nivîsê bi qasî 1,000 tîpan di hûrdemê de têne pîvandin.
| Xizmetkar | Tiştê ku hûn dişînin → tiştê ku hûn distînin | Qûrs |
|---|---|---|
| Veqetandina Deng | Deng → dengê paqij + şopên paşxaneyê | $0.02/deqîqe |
| Veguheztin (STT) | Veguheztina deng → nivîsê bi xalbendî û demjimêra asta peyvan | $0.02/deqîqe |
| Veguheztina Pro | Deng → Veqetandina Deng + Veguheztin (STT), çêtirîn ji bo dengê bi deng | $0.05/deqîqe |
| Werger | Nivîs → nivîsa wergerandî | $0.02/deqîqe |
| Vegotin (TTS) | Nivîs → dengê vegotinê bi dengekî pêşwextkirî | $0.03/deqîqe |
| Wergerandin + Vegotin — dengê pêşwextkirî | Nivîs → wergerandî, paşê bi dengekî pêşwextkirî tê vegotin | $0.06/deqîqe |
| Wergerandin + Vegotin — dengekî hevgirtî | Nivîs + nimûneyek dengî ya ≥1 hûrdemî → wergerandî, dû re bi dengê hevberkirî tê vegotin. Zimanê çavkanî û zimanê armanc divê ji hev cuda bin. | $0.08/deqîqe |
Lokalîzekirina vîdyoyê ya tevahî yek xizmeta API e ku bi planekê ve girêdayî ye: ew ji deqeyên ku di plana we de hene sûd werdigire, dûv re jî bi rêjeya planê zêde dibe. Plan û bihayan bibînin