Иштеп чыгуучу API
Жумуш агымыңызга Addavox локализациясын интеграциялаңыз. Видеону толук локализациялоо үчүн убакыт, сапатты текшерүү, субтитрлер жана сыйкырдуу шилтемелер аркылуу сереп редакторуна толук мүмкүнчүлүк алуу үчүн API видео дубляжын тандаңыз. Ошондой эле, китепти баяндоо же китепти бир эле учурда которуу жана баяндоо сыяктуу башка тапшырмалар үчүн каалаган жеке кызмат APIлерин тандай аласыз.
API Ачкычтар
API ачкычтары Addavox аккаунтуна таандык. Жогорудагы "Жергиликтүүлөштүрүүнү баштоо" баскычы менен ачкыч түзүңүз, андан кийин колдонмодо ачкыч түзүңүз — ар бир чалуу ошол аккаунтка эсептелинет.
Жеке API кызматтары сиздин кредиттик балансыңыздан төлөнөт, аны сиз Addavox аккаунтуңузда толуктап, башкарасыз. Толук видео локализациясы өзгөчөлүк болуп саналат: ал сиз "Пландар жана баалоо" бөлүмүндө тандаган план менен бирдей бааны колдонот — планыңызга мүнөттөр кирет, андан кийин пландын тарифи боюнча ашыкча убакыт берилет.
Негизги URL:
https://api.addavox.com/api/v1
Авторизациянын аталышы:
X- API -Ачкыч: СИЗДИН_АЧКЫЧЫҢЫЗ
Макулдук жана уруксат
Бардык API суроо-талаптары макулдук объектисин жана жогорку деңгээлдеги режим талаасын камтышы керек. Булар чогуу ар бир жумуш орду боюнча сиздин керектүү укуктарга жана баяндамачынын макулдуктарына ээ экениңизди тастыктаган аттестациялык жазууну түзөт.
Режим талаасы үн синтезин аныктайт: "voice_matched" сүйлөөчүнүн үнүн клондоону колдонот, "standard" синтетикалык TTSти колдонот. Эки режим тең бирдей баада — тандоо толугу менен макулдукка жараша болот.
Үн менен дал келтирүү режими — Толук макулдук талап кылынат
Стандарттык режим — Мазмун укуктары гана
Талаа шилтемеси
| Талаа | Түрү | Талап кылынат | Сүрөттөмө |
|---|---|---|---|
| mode | string | Жогорку деңгээлдеги | voice_matched же standard |
| speaker_consent_obtained | boolean | үн менен гана дал келүү | Аныкталуучу сүйлөөчүлөрдүн ачык макулдугу |
| content_rights_confirmed | boolean | Эки режим тең | Мазмунга менчик укугу же жарактуу лицензия |
| eula_accepted | boolean | Эки режим тең | Addavox EULA кабыл алат |
| attested_by | string | Эки режим тең | Жоопкер тараптын электрондук почтасы же идентификатору |
| attested_at | ISO 8601 | Эки режим тең | Сурам берилген учурдан тартып 24 сааттын ичинде |
Макулдук ката коддору
| HTTP | Код | Абал |
|---|---|---|
| 403 | CONSENT_MISSING | Макулдукка каршы эч нерсе жок |
| 403 | CONSENT_INCOMPLETE | attested_by жок же attested_at жараксыз |
| 403 | CONSENT_NOT_AFFIRMED | Укуктар же EULA тастыкталган эмес |
| 403 | CONSENT_EXPIRED | 24 сааттан ашык убакыттан кийин күбөлөндүрүлгөн |
| 403 | SPEAKER_CONSENT_REQUIRED | сүйлөөчүнүн макулдугусуз voice_match иштетилди |
| 400 | INVALID_MODE | Жараксыз режим мааниси |
API Шилтеме
Толук интерактивдүү схема жана кошумча акыркы чекиттер Open API аркылуу жеткиликтүү.
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 Кызматтын баасы
Жеке кызматтар мүнөтүнө эсептелет жана пландын бир бөлүгү эмес — сиз чалган нерсеңиз үчүн гана бирдиктүү баада, жылдык арзандатуусуз төлөйсүз. Планга киргизилген мүнөттөр толук видео локализациясы гана колдонулат. Тексттик кызматтар мүнөтүнө болжол менен 1000 белгини түзөт.
| Кызмат | Эмне жөнөтөсүз → эмне аласыз | Баалоо |
|---|---|---|
| Үндү бөлүү | Аудио → таза үн + фондук тректер | $0.02/мүн |
| Транскрипция (STT) | Аудио → тыныш белгилери жана сөз деңгээлиндеги убакытты көрсөтүү менен тексттин транскрипциясы | $0.02/мүн |
| Профессионалдык транскрипция | Аудио → Үндү бөлүү + транскрипция (STT), ызы-чуулуу аудио үчүн эң жакшы | $0.05/мүн |
| Котормо | Текст → которулган текст | $0.02/мүн |
| Баяндоо (TTS) | Текст → алдын ала коюлган үн менен баяндалган аудио | $0.03/мүн |
| Которуу + Баяндоо — алдын ала даярдалган үн | Текст → которулуп, андан кийин алдын ала коюлган үн менен баяндалат | $0.06/мүн |
| Которуу + Баяндоо — дал келген үн | Текст + ≥1 мүнөттүк үн үлгүсү → которулуп, андан кийин дал келген үн менен баяндалат. Булак жана максаттуу тилдер айырмаланышы керек. | $0.08/мүн |
Толук видео локализациясы - бул планга байланышкан жалгыз API кызматы: ал сиздин планыңызга киргизилген мүнөттөрдү, андан кийин пландын тарифи боюнча ашыкча убакытты колдонот. Тарифтерди жана бааларды көрүү