# Audivra Documentation (full export) > API-first voice and digital human infrastructure — speech, recognition, score beds, cues, lip-synced video, cloning, dub, and agents on one prepaid credit pool. This file contains the complete Audivra documentation corpus in a single Markdown document. For a lightweight index only, fetch http://127.0.0.1:3000/docs/llms.txt. - Generated from: http://127.0.0.1:3000/docs/llms-full.txt - Base URL: http://127.0.0.1:3000 - Authentication: Authorization: Bearer sk_live_… --- # Audivra Documentation > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs **Section:** Overview API-first voice and digital human infrastructure — speech, recognition, score beds, cues, lip-synced video, cloning, dub, and agents on one prepaid credit pool. Creators use Audivra Studio; developers call the same REST API. POST /api/v1/generate (plus batch, estimate, assets) returns a job immediately. TTS, STT, music, SFX, dub, and agents draw one credit wallet. Self-host on local GPU with fast-path routing under 500 characters. ## Meet the models Pick the right engine for latency, language coverage, VRAM footprint, and plan tier — Kokoro for regional TTS, F5/XTTS for cloning, MuseTalk for lip-sync, or local Ollama on your own GPU. ### Popular picks - **Kokoro-82M** (`kokoro-82m`): Ultra-fast, All plans - **F5-TTS** (`f5-tts`): Streaming, All plans - **MuseTalk** (`musetalk`): Moderate, All plans - **Ollama — Qwen2.5 3B** (`ollama-qwen`): Local (<500 chars), Self-hosted Full comparison: http://127.0.0.1:3000/docs/overview/models ## Browse voices Play samples and copy voice_id for Swahili, Hausa, Yoruba, Hindi, and more — the fastest path from docs to your first API call. - **Zuri** (`zuri-sw`): sw-KE — Swahili — WAXAL / OpenBibleTTS - **Umar** (`umar-ha`): ha-NG — Hausa regional voice - **Ezinne** (`ezinne-yo`): yo-NG — Yoruba regional voice - **Swara** (`swara-hi`): hi-IN — Hindi — low VRAM Kokoro-82M Voice library with audio preview: http://127.0.0.1:3000/docs/overview/voices ## Product paths - **Audivra Studio** (http://127.0.0.1:3000/docs/get-started/dashboard): Studio dashboard — playground, avatars, STT, dub, voices, agents, keys, usage, and local-rail billing. Same pipeline as the public API. - **Audivra API** (http://127.0.0.1:3000/docs/get-started/quickstart): REST + WebSocket: hashed keys, POST /api/v1/generate (batch, estimate, assets), TTS/STT/music/SFX/dub/agents, webhooks, metered credits. - **Self-hosted stack** (http://127.0.0.1:3000/docs/guides/self-host-rtx-4090): Run Ollama, Kokoro-82M, and MuseTalk on local or RTX hardware with fast-path routing before cloud GPU. - **Global South payments** (http://127.0.0.1:3000/docs/guides/paystack-mpesa-webhook): Global South users favor Mobile Money (M-Pesa, MTN, Airtel), instant bank rails (Pix, UPI), and e-wallets — not credit cards alone. - **Enterprise & private cloud** (http://127.0.0.1:3000/docs/self-hosted/enterprise): VPC isolation, on-prem GPU clusters, air-gapped inference, and SLA-backed uptime for B2B teams. ## Core concepts - **Voices** (http://127.0.0.1:3000/docs/overview/voices): Preset library, clones, remixes, designed voices, and community listings — each has a voice_id for TTS and generate. - **Avatars** (http://127.0.0.1:3000/docs/concepts/avatars): avatar_id selects a talking-head preset. Lip-sync models include MuseTalk, LivePortrait, and SadTalker. - **Models** (http://127.0.0.1:3000/docs/overview/models): Compare Kokoro, F5-TTS, MuseTalk, and local Ollama — latency, languages, character limits, VRAM, and tier gates. - **Credits** (http://127.0.0.1:3000/docs/concepts/credits): 1 audio character = 1 credit · 1 video second = 10 credits · 1 STT second = 5 credits. Estimate a mix, then checkout on Pix, UPI, or M-Pesa — see /docs/concepts/credits. - **Pricing** (http://127.0.0.1:3000/docs/concepts/pricing): Video-first plans, resolution gates, Studio/Team, Private GPU, and studio grants — all from PRICING_TIERS. ## Architecture Audio and video on GPUs takes 2–30 seconds. POST /api/v1/generate (and batch) returns a job ID immediately; estimate previews credits; Celery/Redis or Modal GPUs render in the background so HTTP never waits on MuseTalk. 1. Studio or an app sends POST /api/v1/generate (text, lipsync input, or POST /api/v1/generate/batch JSONL) with an API key 2. Next.js / FastAPI validates the key, optionally POST /api/v1/estimate, deducts credits, inserts video_jobs, returns job_id (202) 3. Celery or a Modal GPU webhook runs Kokoro/F5-TTS (or a cloned voice_id) → MuseTalk lip-sync → object storage MP4; short TTS can fast-path locally 4. Job moves to completed; clients poll GET /api/v1/jobs/{id}, subscribe to WebSocket progress, or receive signed webhooks | Layer | Detail | | --- | --- | | SaaS (Next.js) | Studio, playground, STT, dub, voices, agents, keys, billing | | Gateway (FastAPI :8080) | Auth, rate limits, Celery queue, generate/batch/estimate | | Inference (:8090 / Modal) | Kokoro/F5 TTS → MuseTalk lip-sync → FFmpeg MP4; fast-path local <500 chars | | Data | Supabase Postgres + RLS, Redis, object storage CDN | ## Capabilities - **Text to speech** (http://127.0.0.1:3000/docs/api/tts): Generate lifelike speech — try WAV or Opus streaming in the browser on the API page. - **Speech to text** (http://127.0.0.1:3000/docs/api/stt): Transcribe uploads or a public audio URL — billed per second. - **Music** (http://127.0.0.1:3000/docs/api/music): Score beds under talking-heads — billed per second from the same prepaid pool. - **Sound effects** (http://127.0.0.1:3000/docs/api/sfx): Short cues muxed with lip-sync — billed per clip. - **Dubbing** (http://127.0.0.1:3000/docs/api/dub): STT, translate, TTS, and lip-sync as one async job. - **Voice library** (http://127.0.0.1:3000/docs/overview/voices): Presets, clones, remixes, designed voices, and community listings — each has a voice_id. - **Talking avatars** (http://127.0.0.1:3000/docs/api/avatars): Async lip-synced MP4 from text — poll jobs or subscribe to SSE events. - **Unified generate** (http://127.0.0.1:3000/docs/api/generate): Text→avatar or video+audio lipsync (URL, upload, asset_id) with sync_mode. - **Media assets** (http://127.0.0.1:3000/docs/api/assets): Reusable library IDs for generate and batch. - **Voice cloning** (http://127.0.0.1:3000/docs/api/voice-cloning): Instant or professional multi-sample clones on paid plans. - **Voice remix** (http://127.0.0.1:3000/docs/api/voice-remix): Prompt-conditioned variants of clones you own. - **Community marketplace** (http://127.0.0.1:3000/docs/api/marketplace): Publish clones and license community voice_id listings. - **Voice design** (http://127.0.0.1:3000/docs/api/voice-design): Describe a voice in text — preview and save on paid plans. - **Voice agents** (http://127.0.0.1:3000/docs/api/agents): Turn-based conversational agents with TTS output. - **Webhooks** (http://127.0.0.1:3000/docs/api/webhooks): Stripe, Paystack, Flutterwave, and dLocal — payload schemas, signatures, retries, and idempotency. - **Errors & limits** (http://127.0.0.1:3000/docs/reference/errors): Central HTTP error codes and quota reference — 401/402/429/502, credits, routing, rate limits. - **Low-bandwidth streaming** (http://127.0.0.1:3000/docs/guides/stream-opus-low-bandwidth): Opus/AAC 48k chunks for mobile networks in the Global South. - **Self-hosted inference** (http://127.0.0.1:3000/docs/self-hosted/local-worker): Route short prompts to local Ollama and Kokoro before cloud GPU. - **Enterprise deployment** (http://127.0.0.1:3000/docs/self-hosted/enterprise): Private VPC, on-prem GPU, air-gapped inference, and SLA tiers for B2B. - **Pricing** (http://127.0.0.1:3000/docs/concepts/pricing): Talking-head minutes, resolution gates, local-rail checkout, Private GPU, and studio grants. - **Changelog & API v1** (http://127.0.0.1:3000/docs/reference/changelog): Release history and stability promise for /api/v1/* integrations. - **SDKs** (http://127.0.0.1:3000/docs/get-started/sdk): Thin TypeScript + Python clients for TTS, unified generate, voices, and jobs. ## Quick examples ```bash curl -X POST http://127.0.0.1:3000/api/v1/tts \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Hello from Audivra","voice_id":"aurora","model":"kokoro-82m"}' \ --output speech.wav ``` ```bash curl -X POST http://127.0.0.1:3000/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Welcome to our launch.","voice_id":"aurora","avatar_id":"studio-host"}' ``` --- # Models > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/overview/models **Section:** Overview TTS, video, and local engines — latency, VRAM, languages, character limits, and tier gates. Per-request text is capped at 5,000 characters on cloud API routes. ## Speech models | model | Name | Latency | Languages | Max text | License | VRAM | Tier | | --- | --- | --- | --- | --- | --- | --- | --- | | kokoro-82m | Kokoro-82M | Ultra-fast | en-US, sw-KE, ha-NG, yo-NG, am-ET, hi-IN, bn-IN, de-DE, it-IT, nl-NL, zu-ZA | 5000 | Apache 2.0 | Low (T4) | All plans | | kokoro | Kokoro | Fast | en-US, en-GB | 5000 | Apache 2.0 | Low | All plans | | f5-tts | F5-TTS | Streaming | en-US, Clone any language (Starter+) | 5000 | MIT | Med | All plans | | xtts-v2 | XTTS v2 | Clone | ja-JP, 17+ clone languages | 5000 | Coqui | Med | Starter+ | | cosyvoice-2 | CosyVoice 2 | Expressive | fr-FR | 5000 | Apache 2.0 | High | Creator Pro+ | ## Video / lip-sync models ### musetalk MuseTalk · Video lip-sync - Latency: Moderate - License: Apache 2.0 - VRAM: Med - Languages: Language-agnostic (audio-driven) - Max text: 5,000 chars - Tier: All plans ### latentsync LatentSync · Fast lip-sync - Latency: Fast - License: Apache 2.0 - VRAM: Low - Languages: Language-agnostic (audio-driven) - Max text: 5,000 chars - Tier: All plans ### liveportrait LivePortrait · Photo expressions - Latency: Moderate - License: Research - VRAM: Med - Languages: Language-agnostic (audio-driven) - Max text: 5,000 chars - Tier: Starter+ ### sadtalker SadTalker · Audio-driven portrait - Latency: Moderate - License: MIT - VRAM: Med - Languages: Language-agnostic (audio-driven) - Max text: 5,000 chars - Tier: All plans ### emo EMO · Expressive generation - Latency: Slow - License: Research - VRAM: High - Languages: Language-agnostic (audio-driven) - Max text: 5,000 chars - Tier: Creator Pro+ ### codeformer CodeFormer · Face enhancement - Latency: Fast - License: Non-commercial - VRAM: Low - Languages: N/A (post-processing) - Max text: 5,000 chars - Tier: Starter+ ## Local / self-hosted ### ollama-qwen Ollama — Qwen2.5 3B · Fast local LLM - Latency: Local (<500 chars) - License: Apache 2.0 - Footprint: ~2.5 GB - Languages: Multilingual - Max text: 500 chars - Tier: Self-hosted ### ollama-llama Ollama — Llama 3.2 3B · Fast local LLM - Latency: Local (<500 chars) - License: Llama 3.2 - Footprint: ~2.5 GB - Languages: Multilingual - Max text: 500 chars - Tier: Self-hosted ### piper-tts Piper TTS · CPU-friendly TTS - Latency: Ultra-fast - License: MIT - Footprint: CPU - Languages: en-US, Regional packs - Max text: 500 chars - Tier: Self-hosted --- # Voice library > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/overview/voices **Section:** Overview Five voice types — presets, clones, remixes, prompt-based design, and community listings. Browse presets, then unlock custom voices on paid plans. Each type returns a voice_id for TTS and generate. Five voice types — presets, clones, remixes, prompt-based design, and community listings. Browse presets, then unlock custom voices on paid plans. Each type returns a voice_id for TTS and generate. ## Voice types - **Preset voices**: Ship with Audivra — regional Swahili, Hausa, Yoruba, Hindi, and more. — /docs/overview/voices#preset-voice-library - **Cloned voices**: Upload 5–10s audio samples to clone any speaker. — /docs/concepts/cloned-voices - **Voice design**: Describe a voice in text — gender, age, accent, tone. — /docs/concepts/voice-design - **Voice remix**: Describe a change to a clone you own — tone, pacing, accent. — /docs/concepts/voice-remix - **Community marketplace**: Publish a ready clone or license someone else's listing as voice_id. — /docs/concepts/marketplace ## Popular regional picks - **Zuri** (`zuri-sw`): sw-KE · Swahili — WAXAL / OpenBibleTTS · sample: "Habari. Karibu kwenye Audivra. Mimi ni Zuri." - **Umar** (`umar-ha`): ha-NG · Hausa regional voice · sample: "Sannu. Ni Umar ne. Barka da zuwa Audivra." - **Ezinne** (`ezinne-yo`): yo-NG · Yoruba regional voice · sample: "Ẹ kú àárọ̀. Emi ni Ezinne. Ẹ káàbọ̀ sí Audivra." - **Swara** (`swara-hi`): hi-IN · Hindi — low VRAM Kokoro-82M · sample: "नमस्ते। मैं स्वरा हूँ। Audivra में आपका स्वागत है।" In the browser, play samples via GET /api/docs/voice-preview?voice_id=… (public, 20 requests/minute per IP). ## African regional | voice_id | Name | Language | Engine | Preview | | --- | --- | --- | --- | --- | | zuri-sw | Zuri | sw-KE | kokoro-82m | Swahili — WAXAL / OpenBibleTTS | | umar-ha | Umar | ha-NG | kokoro-82m | Hausa regional voice | | ezinne-yo | Ezinne | yo-NG | kokoro-82m | Yoruba regional voice | | mekdes-am | Mekdes | am-ET | kokoro-82m | Amharic regional voice | | thando-zu | Thando | zu-ZA | kokoro-82m | Zulu regional voice | ## South Asian | voice_id | Name | Language | Engine | Preview | | --- | --- | --- | --- | --- | | swara-hi | Swara | hi-IN | kokoro-82m | Hindi — low VRAM Kokoro-82M | | tanishaa-bn | Tanishaa | bn-IN | kokoro-82m | Bengali regional voice | ## English | voice_id | Name | Language | Engine | Preview | | --- | --- | --- | --- | --- | | aurora | Aurora | en-US | kokoro | Warm studio narrator | | holloway | Holloway | en-GB | kokoro | Broadcast baritone | | mira | Mira | en-US | f5-tts | Conversational, bright | | nile | Nile | en-US | kokoro-82m | Low-latency API default | ## European | voice_id | Name | Language | Engine | Preview | | --- | --- | --- | --- | --- | | solenne | Solenne | fr-FR | cosyvoice-2 | Expressive, streaming | | klara-de | Klara | de-DE | kokoro-82m | German studio narrator | | marco-it | Marco | it-IT | kokoro-82m | Italian conversational voice | | lotte-nl | Lotte | nl-NL | kokoro-82m | Dutch clear narrator | ## East Asian | voice_id | Name | Language | Engine | Preview | | --- | --- | --- | --- | --- | | kenji | Kenji | ja-JP | xtts-v2 | Multilingual clone-ready | **API:** GET /api/v1/voices Try a voice in the TTS playground: /docs/api/tts --- # Quickstart > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/get-started/quickstart **Section:** Get started Make your first API call in under five minutes. 1. **Create an account** at /signup — a default API key is provisioned automatically. 2. **Copy your API key** from /app/keys. Format: sk_live_ followed by 48 hex characters. 3. **Generate speech** with cURL: ```bash curl -X POST http://127.0.0.1:3000/api/v1/tts \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Hello from Audivra","voice_id":"aurora","model":"kokoro-82m"}' \ --output speech.wav ``` 4. **Generate a talking avatar (async)** — GPU renders take 2–30 seconds; poll for completion: ```bash curl -X POST http://127.0.0.1:3000/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Welcome to our launch.","voice_id":"aurora","avatar_id":"studio-host"}' # Response (202): { "job_id": "…", "status": "PROCESSING", "poll": "/api/v1/jobs/…" } curl http://127.0.0.1:3000/api/v1/jobs/{job_id} \ -H "Authorization: Bearer sk_live_…" ``` 5. **Same credit pool** — speech, STT, music, SFX, avatars, and dub. Preview with POST /api/v1/estimate; batch with POST /api/v1/generate/batch. --- # Authentication > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/get-started/authentication **Section:** Get started All API requests require a Bearer token using your Audivra API key. ## API keys Keys are hashed with SHA-256 at rest. Mint and revoke keys from /app/keys. ```http Authorization: Bearer sk_live_… Content-Type: application/json ``` ## Session auth (dashboard) Browser routes under /app/* use cookie sessions. API routes accept Bearer keys or dashboard sessions. ## Errors - **401 Unauthorized** — missing, malformed, or revoked API key - **402 Payment required** — insufficient plan or routing credits; upgrade or enable overages - **429 Too many requests** — 60 req/min per API key (see http://127.0.0.1:3000/docs/reference/limits) Full error reference: http://127.0.0.1:3000/docs/reference/errors Limits & quotas: http://127.0.0.1:3000/docs/reference/limits --- # SDKs > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/get-started/sdk **Section:** Get started Thin TypeScript and Python clients for TTS, unified generate, voices, and jobs — zero dependencies beyond fetch / stdlib. Thin TypeScript and Python clients for TTS, unified generate, voices, and jobs — zero dependencies beyond fetch / stdlib. ## TypeScript Copy `sdk/typescript/` from the repo or import directly in monorepos. ```typescript import { Audivra } from "./sdk/typescript"; const client = new Audivra({ apiKey: process.env.AUDIVRA_API_KEY!, baseUrl: "http://127.0.0.1:3000", }); const wav = await client.tts("Habari from Audivra", { voice_id: "zuri-sw" }); const job = await client.generate({ text: "Welcome to our launch.", voice_id: "zuri-sw", avatar_id: "studio-host", }); const { voice_id } = await client.createClone([sampleWav], { name: "Founder voice", input: [{ type: "video", url: "…" }, { type: "audio", url: "…" }], }); const ready = await client.waitUntilReady(voice_id); const cloned = await client.tts("Hello from my clone", { voice_id: ready.id }); ``` ## Python ```bash pip install ./sdk/python ``` ```python from audivra import Audivra client = Audivra(api_key="sk_live_…", base_url="http://127.0.0.1:3000") wav = client.tts("Habari from Audivra", voice_id="zuri-sw") job = client.generate(text="Welcome.", voice_id="zuri-sw", avatar_id="studio-host") status = client.get_job(job["job_id"]) queued = client.create_clone(["sample.wav", "sample-2.wav"], name="Founder voice") ready = client.wait_until_ready(queued["voice_id"]) cloned = client.tts("Hello from my clone", voice_id=ready["id"]) ``` Unified generate covers TTS + lip-sync video in one call — unlike split audio/video APIs. --- # Audivra Studio > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/get-started/dashboard **Section:** Get started Studio — playground, STT, dub, voices, agents, keys, usage, analytics, billing, settings. | Section | Path | Description | | --- | --- | --- | | Playground | /app/playground | Test TTS and async generate without writing code. | | Avatars studio | /app/avatars | Create talking-head videos from text with live job progress. | | Speech to text | /app/stt | Upload audio for transcription or dictate in the browser. | | Dubbing | /app/dub | Transcribe, translate, TTS, and lip-sync in a target language (STT allowlist). | | Voices | /app/voices | Presets, clones, remix, design, marketplace KYC, and seller payouts. | | Agents | /app/agents | Configure conversational voice agents with custom instructions. | | API keys | /app/keys | Mint, label, and revoke sk_live_ keys for production. | | Usage | /app/usage | Character, video-second, and credit consumption by job. | | Analytics | /app/analytics | Traffic and generation mix for the current workspace. | | Usage & billing | /app/billing | Usage calculator, credit balance, plan tiers, and local-rail checkout. | | Settings | /app/settings | Profile, MFA, and workspace preferences. | | Admin | /admin | User approvals, RBAC, security alerts, audit log, and marketplace moderation. | ## Admin control center Local next dev opens registration and auto-approves until platform settings are saved. Operators in ADMIN_EMAILS and info.commgad@gmail.com skip invitation codes, login lockouts, and auth rate limits. The first sign-in creates the operator account if needed, auto-approves it, assigns Super Admin, and grants the Developer API plan. Open /admin for users, invitations, RBAC, and settings. --- # Install the app > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/get-started/install **Section:** Get started Progressive web app — add Audivra to the home screen on phone, tablet, or desktop. ## Add to home screen Use the browser Share or Install app control. Standalone display uses the web manifest and 192/512 icons. ## Offline shell Service worker at /sw.js precaches the home shell. API routes, /_next/*, and App Router RSC fetches are never intercepted. --- # Cloned voices > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/cloned-voices **Section:** Concepts Instant and professional voice cloning from audio samples on paid plans. Instant cloning uploads 1–5 short WAV/MP3 samples. Professional cloning (Creator Pro+) trains on 5–25 files covering 2–30 minutes of speech. Both return a voice_id for TTS and avatar generation. API: POST /api/voices/clone (kind=instant|professional) Studio: /app/voices → Cloned voices tab --- # Voice remix > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/voice-remix **Section:** Concepts Create a new custom voice from a clone you own using a natural-language prompt. Pass a prompt such as “slightly deeper and slower, late-night radio host.” Audivra applies prompt DSP, then a neural restyle when F5/XTTS weights are installed, and trains a new clone slot. The parent stays unchanged. API: POST /api/v1/voices/{id}/remix Studio: /app/voices → Remix tab --- # Community marketplace > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/marketplace **Section:** Concepts Share ready clones and license community listings as voice_id. Publish a clone you recorded (or have permission to share). Paid listings require KYC; production paid publishes wait for moderation. Per-use fees credit sellers 70%. Sellers request payouts from earned credits. Licensed buyers can rate listings. Browse: GET /api/v1/voices/community Publish: POST /api/voices/clone/{id}/publish Studio: /app/voices → Marketplace tab --- # Voice design > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/voice-design **Section:** Concepts Create a custom voice from a natural-language description. Describe gender, age, accent, and tone. Audivra seeds a speaker from the prompt, applies style DSP, then trains a clone embedding (neural restyle when GPU weights are installed). Preview: POST /api/voices/design/preview Save: POST /api/voices/design Studio: /app/voices → Voice design tab --- # Voices (redirect) > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/voices **Section:** Concepts Deprecated — see /docs/overview/voices for presets, clones, remix, design, and marketplace. Canonical URL: /docs/overview/voices --- # Avatars > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/avatars **Section:** Concepts avatar_id selects a talking-head preset and default lip-sync model. Photo-based avatars use LivePortrait or SadTalker. Video-reference avatars use MuseTalk. Upload custom sources via POST /api/v1/avatar/source. | avatar_id | Name | Mode | Model | Expression | | --- | --- | --- | --- | --- | | studio-host | Studio Host | photo | liveportrait | Neutral, steady eye contact | | sales-closer | Sales Closer | video | musetalk | Confident, subtle smiles | | support-agent | Support Agent | photo | sadtalker | Calm, empathetic | | creator-emo | Creator EMO | photo | emo | Dynamic — laughs and emphasis | **API:** GET /api/v1/avatars --- # Credits > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/credits **Section:** Concepts Credits meter consumption across TTS, video, and fast-path routing. - **1 audio character = 1 credit** - **1 video second = 10 credits** - **1 STT second = 5 credits** ## Estimate your usage Speech, recognition, score beds, cues, and talking-head minutes share one credit pool. Checkout on Pix, UPI, M-Pesa, or cards. - 1 audio character = 1 credit - 1 video second = 10 credits (600 credits per avatar minute) - 1 STT second = 5 credits - 1 music second = 8 credits - 1 sound-effect clip = 20 credits - Spoken-audio estimate: 600 characters ≈ 1 minute Example (defaults): - 40,000 audio characters + 15 avatar minutes = 49,000 credits - Equivalent pool: 49,000 audio characters or 82 min of avatar video - Recommended plan: Creator Pro ($18/mo) Checkout: POST /api/billing/checkout with plan + provider (dlocal · paystack · flutterwave · ebanx · yellowcard · stripe). Interactive calculator: /docs/concepts/credits and the homepage #pricing section. ## Plans | Plan | Price | Credits/mo | Highlights | | --- | --- | --- | --- | | Free Trial | $0/mo | 12,000 | 12,000 credits/mo (~20 min audio OR ~20 min video) | | Starter / Hobby | $5/mo | 36,000 | 36,000 credits/mo · commercial usage rights | | Creator Pro | $18/mo | 145,000 | 145,000 credits/mo · 1080p video · 3 custom clones | | Developer API | $79/mo | 720,000 | 720,000 credits/mo · REST API keys & webhooks | ## Custom voice slots Each voice clone you create consumes one custom voice slot on your plan. Deleting a clone frees the slot. Preset library voices do not use slots. ## Free tier Generous free tier — top up anytime to keep building - Non-commercial license — attribution required for any public use - No custom voice cloning without a paid plan - Audio capped at 128 kbps (HD on paid tiers) - 12,000 credits/mo included — add prepaid funds to continue beyond quota ## Pay As You Go - All self-serve tiers — minimum $5 top-up · pause at $0 · no postpaid debt - Creator: 145,000 credits/mo — PAYG at $0.035/1k after quota - Developer: 720,000 credits/mo — volume PAYG at $0.032/1k See /docs/concepts/pay-as-you-go for full PAYG documentation. --- # Pricing > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/pricing **Section:** Concepts Talking-head minutes, compare table, Private GPU, and studio grants. Talking-head minutes first. Speech, recognition, score beds, and cues share the same prepaid pool. Pay with Pix, UPI, M-Pesa, or cards. ## Audio products - **Text to speech** (/docs/api/tts): Scripts to WAV/Opus. Characters draw the same pool as avatars. - **Speech to text** (/docs/api/stt): Upload clips for transcripts and dubbing. Billed per recognized second. - **Music** (/docs/api/music): Score beds under talking-heads — not a separate Western music SKU. - **Sound effects** (/docs/api/sfx): Short cues muxed with lip-sync. Billed per clip from the prepaid wallet. ## Plans - **Free Trial** ($0/mo) — ~20 min talking-head · 480p watermarked · 12,000 credits - **Starter / Hobby** ($5/mo) — ~60 min talking-head · 720p clean export · 36,000 credits - **Creator Pro** ($18/mo) — ~242 min talking-head · 1080p clean export · 145,000 credits - **Developer API** ($79/mo) — ~1200 min talking-head · 1080p clean export · 720,000 credits ## Compare plans - **Talking-head minutes** — Free Trial: ~20 min · Starter / Hobby: ~60 min · Creator Pro: ~242 min · Developer API: ~1200 min - **Audio characters** — Free Trial: 12,000 · Starter / Hobby: 36,000 · Creator Pro: 145,000 · Developer API: 720,000 - **Resolution** — Free Trial: 480p · Starter / Hobby: 720p · Creator Pro: 1080p · Developer API: 1080p - **Watermark** — Free Trial: Logo on video · Starter / Hobby: None · Creator Pro: None · Developer API: None - **Commercial license** — Free Trial: Attribution only · Starter / Hobby: Yes · Creator Pro: Yes · Developer API: Yes - **Custom voice slots** — Free Trial: 0 · Starter / Hobby: 1 · Creator Pro: 3 · Developer API: 10 - **PAYG after quota** — Free Trial: $0.040/1k · pause at $0 · Starter / Hobby: $0.040/1k · pause at $0 · Creator Pro: $0.035/1k · pause at $0 · Developer API: $0.032/1k · pause at $0 - **Fast-path local TTS** — Free Trial: Included under 500 chars · Starter / Hobby: Included under 500 chars · Creator Pro: Included under 500 chars · Developer API: Priority GPU · local <500 chars - **API** — Free Trial: REST included · Starter / Hobby: REST included · Creator Pro: REST included · Developer API: Keys, webhooks, volume - **Score bed minutes (pool)** — Free Trial: 25 min · Starter / Hobby: 75 min · Creator Pro: 302 min · Developer API: 1500 min - **SFX clips (pool)** — Free Trial: 600 clips · Starter / Hobby: 1,800 clips · Creator Pro: 7,250 clips · Developer API: 36,000 clips ## Studio / Team Seat-based access, one credit wallet, still prepaid. Not a sixth Western volume SKU — you keep Creator or Developer credits and add seats. ## Private GPU Dedicated RTX/A100 nodes run inference/main.py and local_worker.py. Fast-path routing sends short prompts to local Kokoro/Ollama; heavy lip-sync stays on-cluster MuseTalk workers. ## Studio grants A year of prepaid credits plus a commercial license — billed as talking-head minutes and audio characters, checked out on local rails. Apply with a short production brief, not a character dump. ## FAQ ### How do talking-head minutes and audio characters share a pool? 1 audio character = 1 credit. 1 video second = 10 credits. 1 STT second = 5 credits. 1 music second = 8 credits. 1 sound-effect clip = 20 credits. One prepaid pool — spend it on avatars, speech, recognition, score beds, or cues. ~20 min talking-head · 480p watermarked on Free Trial if you spend the pool on video. ### Are music and sound effects extra SKUs? No. Tabs on the pricing page switch the estimator. Score beds and cues still draw the same monthly credits and local-rail checkout as TTS and talking-heads. ### Do unused credits roll over? Subscription credits reset each billing cycle. Prepaid PAYG funds stay for 12 months and pause at $0 — no surprise invoice. Downgrade or cancel drops unused plan credits at cycle end. ### Can I pay annually? Paid self-serve plans can convert to annual after signup — pay 10 months, cover 12. Checkout starts monthly. ### Which local rails can I use? Pix, UPI, M-Pesa, MTN, Airtel, OXXO, PSE, and USDC ramps — pick a rail on the pricing cards or calculator. Cards remain a fallback. ### What is fast-path local routing? Prompts under 500 characters stay on local Kokoro/Ollama when the worker is healthy. Longer scripts and lip-sync video go to cloud GPU. Same credit pool; routing cost is separate and small. ### Is there a team plan? Studio / Team adds seats and a shared avatar library on top of Creator Pro or Developer. Credits stay prepaid. Write sales with seat count and monthly avatar minutes. ### Can I run Audivra on my own GPU? Yes. Private GPU is a license for RTX-class or air-gapped nodes. SaaS credits are optional if inference stays on your hardware. ### Who are studio grants for? African and LATAM creator studios, campus labs, and public-interest newsrooms. A year of prepaid credits plus a commercial license — billed as talking-head minutes and audio characters, checked out on local rails. Apply with a short production brief, not a character dump. --- # Pay As You Go > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/pay-as-you-go **Section:** Concepts Prepaid top-ups extend monthly quota on all self-serve tiers. All self-serve tiers — minimum $5 top-up · pause at $0 · no postpaid debt ## Rates - Free Trial: $0.040/1k chars - Starter / Hobby: $0.040/1k chars - Creator Pro: $0.035/1k chars - Developer API: $0.032/1k chars ## Top-up - POST /api/billing/topup — minimum $5 - GET/PUT /api/billing/payg-settings — auto top-up - PAYG funds expire after 12 months --- # Processing nodes > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/concepts/processing-nodes **Section:** Concepts Short prompts route to local Ollama (LLM), Kokoro/Piper (TTS), and MuseTalk/Wav2Lip (lip-sync) before offloading to GPU cluster or external APIs. Every execution is logged in PostgreSQL with atomic credit deduction. | Node | Description | When used | Routing cost | | --- | --- | --- | --- | | local_worker | Ollama LLM, Kokoro/Piper TTS, MuseTalk on local or RTX GPU | Prompt under 500 chars, worker healthy | 1 credit | | gpu_cluster | Celery workers or Modal T4/A10G serverless GPUs | Long scripts, lip-sync video, VRAM saturated | 3 credits | | external_api | Third-party fallback when EXTERNAL_API_URL is set | forceCloud=true or failover | 3 credits | ## Open-source stack - **Fast LLM:** Ollama — qwen2.5:3b / llama3.2:3b (~2.5 GB VRAM/RAM) - **TTS:** Kokoro-82M or Piper TTS (~500 MB RAM / CPU-friendly) - **Lip-sync video:** MuseTalk or Wav2Lip (~4 GB VRAM) --- # OpenAPI reference > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/openapi **Section:** API reference OpenAPI 3.0 spec and Postman collection for import, codegen, and agent tooling. Download the machine-readable API surface: - **OpenAPI 3.0:** http://127.0.0.1:3000/docs/openapi.json - **Postman collection v2.1:** http://127.0.0.1:3000/docs/postman.json **69 documented operations** across TTS, generate, avatars, voice cloning, agents, billing, webhooks, and dashboard helpers. ## Import ```bash # Postman → Import → Link http://127.0.0.1:3000/docs/postman.json # Or save locally curl -o audivra-openapi.json http://127.0.0.1:3000/docs/openapi.json curl -o audivra-postman.json http://127.0.0.1:3000/docs/postman.json ``` | Method | Path | Tag | | --- | --- | --- | | GET | /api/v1/changelog | Dashboard | | POST | /api/v1/tts | Text to speech | | POST | /api/v1/tts/stream | Text to speech | | POST | /api/v1/stt | Speech to text | | GET | /api/v1/stt | Speech to text | | POST | /api/v1/music | Music | | POST | /api/v1/sfx | Sound effects | | POST | /api/v1/dub | Dubbing | | POST | /api/v1/generate | Generate | | POST | /api/v1/generate/batch | Generate | | POST | /api/v1/estimate | Generate | | GET | /api/v1/generate/batch/{id} | Generate | | POST | /api/v1/assets | Assets | | GET | /api/v1/assets | Assets | | GET | /api/v1/assets/{id} | Assets | | PATCH | /api/v1/assets/{id} | Assets | | DELETE | /api/v1/assets/{id} | Assets | | GET | /api/v1/assets/{id}/file | Assets | | GET | /api/v1/voices | Voices | | POST | /api/voices/clone | Voice cloning | | GET | /api/voices/clone | Voice cloning | | PATCH | /api/voices/clone/{id} | Voice cloning | | DELETE | /api/voices/clone/{id} | Voice cloning | | POST | /api/voices/clone/{id}/publish | Marketplace | | DELETE | /api/voices/clone/{id}/publish | Marketplace | | POST | /api/v1/voices/{id}/remix | Voice remix | | GET | /api/v1/voices/community | Marketplace | | GET | /api/v1/voices/community/{id} | Marketplace | | POST | /api/v1/voices/community/{id} | Marketplace | | GET | /api/v1/voices/community/{id}/preview | Marketplace | | GET | /api/v1/voices/community/{id}/reviews | Marketplace | | POST | /api/v1/voices/community/{id}/reviews | Marketplace | | POST | /api/voices/design | Voice design | | GET | /api/voices/design | Voice design | | POST | /api/voices/design/preview | Voice design | | DELETE | /api/voices/design/{id} | Voice design | | POST | /api/v1/avatar | Avatars & jobs | | GET | /api/v1/avatar | Avatars & jobs | | GET | /api/v1/jobs/{id} | Avatars & jobs | | GET | /api/v1/jobs/{id}/events | Avatars & jobs | | GET | /api/v1/avatar/{id}/video | Avatars & jobs | | GET | /api/v1/avatars | Avatars & jobs | | POST | /api/v1/avatar/source | Avatars & jobs | | POST | /api/v1/agents/turn | Agents | | POST | /api/billing/checkout | Billing | | POST | /api/billing/topup | Billing | | GET | /api/billing/payg-settings | Billing | | PUT | /api/billing/payg-settings | Billing | | POST | /api/webhooks/stripe | Webhooks | | POST | /api/webhooks/paystack | Webhooks | | POST | /api/webhooks/flutterwave | Webhooks | | POST | /api/webhooks/dlocal | Webhooks | | GET | /api/v1/avatar/{id} | Avatars & jobs | | GET | /api/v1/voices/clone/{id}/sample | Voice cloning | | GET | /api/v1/avatar/source/{id} | Avatars & jobs | | GET | /api/analytics | Dashboard | | PATCH | /api/settings | Dashboard | | GET | /api/me | Dashboard | | GET | /api/keys | Dashboard | | POST | /api/keys | Dashboard | | DELETE | /api/keys | Dashboard | | GET | /api/usage | Dashboard | | GET | /api/health | Dashboard | | GET | /api/voices/kyc | Marketplace | | POST | /api/voices/kyc | Marketplace | | GET | /api/voices/payouts | Marketplace | | POST | /api/voices/payouts | Marketplace | | GET | /api/admin/moderation | Dashboard | | POST | /api/admin/moderation | Dashboard | --- # POST /api/v1/generate > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/generate **Section:** API reference Unified generate — async video jobs, fast-path local TTS/LLM, GPU cluster offload. ## Try it Interactive playground on http://127.0.0.1:3000/docs/api/generate — submit POST /api/v1/generate with session auth or a pasted sk_live_ key, watch job status, and preview video. ### POST /api/v1/generate Validates credits, routes to local_worker or gpu_cluster, deducts routing credits atomically. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `text` | string | yes | Input prompt or script (alias: prompt) | | `voice_id` | string | no | Preset voice ID or ready clone UUID | | `avatar_id` | string | no | Avatar preset (default: default) | | `taskType` | string | no | tts · llm_inference · lip_sync · unified | | `forceCloud` | boolean | no | Skip local worker and use GPU cluster | | `model` | string | no | TTS model (default: kokoro-82m) | | `video_model` | string | no | Lip-sync model (default: musetalk) | **Request body:** ```json { "text": "Habari from Audivra", "voice_id": "zuri-sw", "avatar_id": "studio-host", "taskType": "unified" } ``` **Response:** ```json // Async (202) { "success": true, "job_id": "abc123", "status": "PROCESSING", "poll": "/api/v1/jobs/abc123", "meta": { "executedBy": "gpu_cluster", "routingCreditsDeducted": 3 } } // Sync (200) fast-path { "success": true, "data": "…", "meta": { "executedBy": "local_worker", "creditsDeducted": 1 } } ``` **Errors:** | Code | Meaning | | --- | --- | | 401 | Invalid or missing API key | | 402 | Insufficient routing or plan credits | | 409 | Voice clone still training | | 502 | Local worker or gateway unavailable | ```bash curl -X POST http://127.0.0.1:3000/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -d '{"text":"Hello","taskType":"tts","voice_id":"aurora"}' ``` --- # POST /api/v1/generate/batch > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/generate-batch **Section:** API reference Paid queue of talking-head jobs. Not parallel GPU renders. ### POST /api/v1/generate/batch Starter+ only. JSON items, JSONL, dry_run, webhook_url. Poll GET /api/v1/generate/batch/{id}. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `items` | array | yes | text plus optional voice_id, avatar_id, model, video_model | **Request body:** ```json { "items": [{ "text": "Hello from Audivra" }] } ``` **Errors:** | Code | Meaning | | --- | --- | | 403 | Free Trial or over plan batch cap | | 429 | Generate rate bucket | ```bash curl -X POST http://127.0.0.1:3000/api/v1/generate/batch \ -H "Authorization: Bearer sk_live_…" \ -d '{"items":[{"text":"Hello from Audivra"}]}' ``` --- # POST /api/v1/estimate > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/estimate **Section:** API reference Preview credits and plan caps before spending. ### POST /api/v1/estimate kind: tts, stt, video, dub, or lipsync. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | no | tts · stt · video · dub | | `text` | string | no | Script | | `duration_seconds` | number | no | Media length | **Request body:** ```json { "kind": "video", "text": "Studio intro" } ``` **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | ```bash curl -X POST http://127.0.0.1:3000/api/v1/estimate \ -H "Authorization: Bearer sk_live_…" \ -d '{"kind":"stt","duration_seconds":90}' ``` --- # Assets > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/assets **Section:** API reference Reusable video, audio, and image library referenced by asset_id. ### POST /api/v1/assets Multipart file or JSON url. Then pass asset_id into generate input[]. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `file` | file | no | Multipart upload | | `url` | string | no | Public https URL | **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | ```bash curl -X POST http://127.0.0.1:3000/api/v1/assets -H "Authorization: Bearer sk_live_…" -F "file=@clip.mp4" ``` --- # Text to speech > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/tts **Section:** API reference Generate speech audio from text — WAV response or low-bandwidth Opus/AAC streaming. ## Try it Interactive playground on http://127.0.0.1:3000/docs/api/tts — hear WAV or Opus output in the browser with session auth or a pasted sk_live_ key. Browse preset voices with play sample + copy voice_id: http://127.0.0.1:3000/docs/overview/voices ### POST /api/v1/tts Returns audio/wav. Meters len(text) against plan character quota. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `text` | string | yes | Text to synthesize | | `voice_id` | string | no | Preset ID or ready clone UUID | | `model` | string | no | kokoro-82m · f5-tts · xtts-v2 | **Request body:** ```json { "text": "Hello from Audivra", "voice_id": "aurora", "model": "kokoro-82m" } ``` **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | | 402 | Character quota exceeded | | 409 | Voice clone still training | ### POST /api/v1/tts/stream Chunked Opus/AAC streaming for mobile networks and Global South low-bandwidth regions. ```bash curl -X POST http://127.0.0.1:3000/api/v1/tts/stream \ -H "Authorization: Bearer sk_live_…" \ -d '{"text":"Sentence one.","voice_id":"zuri-sw","format":"opus"}' \ --output stream.opus ``` --- # Speech to text > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/stt **Section:** API reference Transcribe uploaded audio or a public audio URL. Credits billed per second of duration. ## Try it Interactive upload on http://127.0.0.1:3000/docs/api/stt. ### POST /api/v1/stt Multipart audio or JSON audio_url (SSRF-checked). Duration and size follow the caller plan (3 min / 15 MB on Free Trial; up to 30 min on paid). **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `audio` | file | no | WAV, MP3, M4A, OGG, FLAC, WebM | | `audio_url` | string | no | Public https URL | | `language` | string | no | auto or allowlisted ISO 639-1 (en, de, it, nl, fr, es, pt, pl, … (33 total)) | **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | | 402 | Credit quota exceeded | | 503 | Whisper engine not installed | ## Allowlisted languages ### Detection - `auto` — Detect automatically ### English - `en` — English ### Europe - `de` — German - `it` — Italian - `nl` — Dutch - `fr` — French - `es` — Spanish - `pt` — Portuguese - `pl` — Polish - `ru` — Russian - `uk` — Ukrainian - `tr` — Turkish ### Africa - `sw` — Swahili - `ha` — Hausa - `yo` — Yoruba - `am` — Amharic - `zu` — Zulu - `xh` — Xhosa - `af` — Afrikaans - `tw` — Twi - `ig` — Igbo ### Middle East - `ar` — Arabic - `ur` — Urdu ### South Asia - `hi` — Hindi - `bn` — Bengali - `ta` — Tamil - `te` — Telugu ### East Asia - `zh` — Chinese (Mandarin) - `ja` — Japanese - `ko` — Korean ### Southeast Asia - `id` — Indonesian - `vi` — Vietnamese - `th` — Thai - `ms` — Malay ## GET /api/v1/stt Language catalog and upload caps. ```bash curl -X POST http://127.0.0.1:3000/api/v1/stt \ -H "Authorization: Bearer sk_live_…" \ -F "audio=@clip.wav" \ -F "language=auto" ``` --- # Music > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/music **Section:** API reference Score beds billed per second from the prepaid pool. ## POST /api/v1/music ### POST /api/v1/music JSON prompt + seconds (2–20). Returns audio/wav. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | yes | Bed description | | `seconds` | number | no | Duration 2–20 | **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | | 402 | Credit quota exceeded | ```bash curl -X POST http://127.0.0.1:3000/api/v1/music \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"prompt":"soft kora under a news open","seconds":8}' \ --output bed.wav ``` --- # Sound effects > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/sfx **Section:** API reference Short cues billed per clip from the prepaid wallet. ## POST /api/v1/sfx ### POST /api/v1/sfx JSON prompt. Returns audio/wav. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | yes | Cue description | **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | | 402 | Credit quota exceeded | ```bash curl -X POST http://127.0.0.1:3000/api/v1/sfx \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"prompt":"soft whoosh into a studio sting"}' \ --output cue.wav ``` --- # Dubbing > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/dub **Section:** API reference Async STT → translate → TTS → lip-sync. Poll GET /api/v1/jobs/{id}. ## Pipeline Recognition meters STT seconds. Translation uses the local LLM worker. Speech and lip-sync follow the avatar job. ### POST /api/v1/dub Multipart source. Optional script skips recognition. Returns 202 + job_id. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `source` | file | yes | Audio or talking-head video | | `target_language` | string | no | Allowlisted code | | `voice_id` | string | no | Preset or ready clone | | `script` | string | no | Skip STT | **Errors:** | Code | Meaning | | --- | --- | | 401 | Unauthorized | | 402 | Quota exceeded | | 503 | STT or translation worker unavailable | ```bash curl -X POST http://127.0.0.1:3000/api/v1/dub \ -H "Authorization: Bearer sk_live_…" \ -F "source=@talking-head.mp4" \ -F "target_language=sw" \ -F "voice_id=zuri-sw" ``` --- # Avatars & jobs > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/avatars **Section:** API reference Create lip-synced talking-head videos asynchronously — poll status or subscribe to SSE. ### POST /api/v1/avatar Dashboard-friendly avatar job — returns 202 + job_id with SSE pipeline updates. **Auth:** Bearer API key required **Request body:** ```json { "text": "Welcome to our product launch.", "voice_id": "aurora", "avatar_id": "studio-host", "video_model": "musetalk" } ``` **Response:** ```json { "job_id": "…", "status": "queued", "events": "/api/v1/jobs/{id}/events" } ``` ### GET /api/v1/jobs/{id} Poll job status, duration, and output URL when completed. **Auth:** Bearer API key required ### GET /api/v1/jobs/{id}/events Server-sent events for live pipeline progress (tts → lipsync → render). **Auth:** Bearer API key required ### GET /api/v1/avatar/{id}/video Download completed MP4 when job status is completed. **Auth:** Bearer API key required ### GET /api/v1/avatars List avatar presets and supported video models. **Auth:** None ```bash JOB=$(curl -s -X POST http://127.0.0.1:3000/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -d '{"text":"Hello","voice_id":"aurora","avatar_id":"studio-host"}' | jq -r .job_id) curl http://127.0.0.1:3000/api/v1/jobs/$JOB -H "Authorization: Bearer sk_live_…" ``` --- # Voice cloning > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/voice-cloning **Section:** API reference Upload a short audio sample to train a custom voice on paid plans. ## Custom voice slots Each clone consumes one slot on your plan. DELETE frees the slot. Preset library voices do not use slots. - Starter: 1 slot - Creator: 3 slots - Developer: 10 slots - Free: cloning not available ### POST /api/voices/clone Multipart upload. Instant: 1–5 short samples. Professional (Creator+): 5–25 files covering 2–30 minutes. Pass kind=professional. Bearer sk_live_… or session. Optional webhook_url. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Display name for the clone | | `kind` | string | no | instant (default) or professional (Creator+) | | `sample / samples` | file | yes | Audio samples (WAV/MP3). Instant: under 8 MB each. Professional: under 32 MB each. | | `engine` | string | no | f5-tts (default) or xtts-v2 | | `language` | string | no | ISO language code (default: en) | | `webhook_url` | string | no | POST target for clone.ready / clone.failed | **Response:** ```json { "clone": { "id": "3f2c9a1e-…", "name": "Founder voice", "status": "queued", "engine": "f5-tts" }, "voice_id": "3f2c9a1e-…", "samples_uploaded": 2, "poll": "/api/voices/clone" } ``` **Errors:** | Code | Meaning | | --- | --- | | 401 | Missing session or API key | | 402 | Free plan or custom voice slot limit reached | ### GET /api/voices/clone List your voice clones and training status. ### PATCH /api/voices/clone/{id} Rename a clone you own. Preview the sample with GET /api/v1/voices/clone/{id}/sample. ### DELETE /api/voices/clone/{id} Delete a clone and free a custom voice slot. When status is `ready`, pass the clone UUID as `voice_id` in TTS and generate requests. Webhooks: `clone.ready` and `clone.failed` — see /docs/api/webhooks. --- # Voice remix > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/voice-remix **Section:** API reference Create a new custom voice from a clone you own using a natural-language prompt. ### POST /api/v1/voices/{id}/remix JSON body with prompt. Parent must be a ready clone you own. Consumes one custom voice slot. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | yes | Parent clone UUID | | `prompt` | string | yes | How to change the voice | | `name` | string | no | Display name for the remix | **Request body:** ```json { "prompt": "Slightly deeper and slower.", "name": "Founder — warmer" } ``` **Response:** ```json { "voice_id": "8c1a…", "parent_id": "3f2c…", "status": "queued" } ``` **Errors:** | Code | Meaning | | --- | --- | | 402 | No custom voice slot remaining | | 409 | Parent clone is not ready | --- # Community marketplace > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/marketplace **Section:** API reference Publish ready clones and license community listings as voice_id. ### GET /api/v1/voices/community Browse published listings. Filter with query, language, or tag. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `query` | string | no | Search text | | `language` | string | no | ISO language code | | `tag` | string | no | Single tag | | `sort` | string | no | featured (default), popular, or recent | **Errors:** | Code | Meaning | | --- | --- | | 401 | Missing session or API key | Publish: POST /api/voices/clone/{id}/publish with consent: true (stores a consent record). Paid listings: POST /api/voices/kyc first. Production paid publishes stay pending until GET/POST /api/admin/moderation. Payouts: GET/POST /api/voices/payouts (minimum 100 earned credits). License: POST /api/v1/voices/community/{id}. Rate: POST /api/v1/voices/community/{id}/reviews (licensed buyers). Sellers receive 70% of price_credits on each TTS use. Use the listing UUID as voice_id in TTS. --- # Voice design > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/voice-design **Section:** API reference Generate a custom voice from a natural-language description on paid plans. ## Custom voice slots Designed voices share the same slot pool as clones. ### POST /api/voices/design/preview Sync preview WAV — does not consume a slot. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | yes | Voice description (8–2000 chars) | | `gender` | string | no | male | female | neutral | | `engine` | string | no | f5-tts (default) or xtts-v2 | **Response:** ```json audio/wav body ``` **Errors:** | Code | Meaning | | --- | --- | | 502 | Inference worker unavailable | ### POST /api/voices/design Create a designed voice from a text prompt. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | yes | Voice description | | `name` | string | no | Display name | | `webhook_url` | string | no | POST target for design.ready / design.failed | **Response:** ```json { "design": { "id": "8a1b2c3d-…", "name": "Product narrator", "status": "queued" }, "voice_id": "8a1b2c3d-…", "poll": "/api/voices/design" } ``` **Errors:** | Code | Meaning | | --- | --- | | 401 | Missing session or API key | | 402 | Free plan or custom voice slot limit reached | Webhooks: `design.ready` and `design.failed`. --- # Voice agents > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/agents **Section:** API reference Turn-based conversational agents that return text replies and optional TTS audio. ### POST /api/v1/agents/turn Send a user message; receive agent reply with synthesized speech when available. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `message` | string | yes | User utterance or text input | | `agent_id` | string | no | Preset or custom agent configuration | | `voice_id` | string | no | TTS voice for spoken reply | **Request body:** ```json { "message": "What is included in the free plan?", "agent_id": "support", "voice_id": "aurora" } ``` **Response:** ```json { "reply": "Free trial includes 12,000 credits per month. PAYG top-up from $5 extends usage beyond quota.", "audio_url": null } ``` ## Built-in presets - **support:** You are a helpful Audivra support agent. Be concise and accurate. Knowledge: Free trial: 12,000 credits/mo, watermarked, non-commercial. PAYG top-up from $5 at $0.04/1k. Paid from $5/mo (Starter) with commercial license. 1 char = 1 credit, 1 video sec = 10 credits. - **sales:** You explain Audivra pricing and help developers integrate the API. Knowledge: Tiers: Free (12k credits), Starter $5 (36k), Creator Pro $18 (145k, PAYG $0.035/1k, 50% off first month), Developer $79 (720k, priority GPU, PAYG $0.032/1k). Voice cloning on paid plans only. Configure agents in the dashboard at /app/agents. --- # Developer exports > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/reference/developer-exports **Section:** Reference Download or fetch machine-readable documentation and API specs. These files are for AI agents, IDE plugins, Postman, Insomnia, and client codegen — not meant to be read as HTML pages in the browser. Download or fetch machine-readable documentation and API specs. ## Exports - **llms.txt** (Markdown): http://127.0.0.1:3000/docs/llms.txt — Doc index for AI agents and IDE plugins - **llms-full.txt** (Markdown): http://127.0.0.1:3000/docs/llms-full.txt — Complete documentation corpus in a single Markdown file - **openapi.json** (JSON): http://127.0.0.1:3000/docs/openapi.json — OpenAPI 3.0 — Postman, Insomnia, and client codegen - **postman.json** (JSON): http://127.0.0.1:3000/docs/postman.json — Importable Postman Collection v2.1 ## curl ``` curl -o llms.txt http://127.0.0.1:3000/docs/llms.txt curl -o llms-full.txt http://127.0.0.1:3000/docs/llms-full.txt curl -o audivra-openapi.json http://127.0.0.1:3000/docs/openapi.json curl -o audivra-postman.json http://127.0.0.1:3000/docs/postman.json ``` --- # Errors > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/reference/errors **Section:** Reference HTTP status codes, JSON error bodies, and recovery steps for the Audivra API — 401 auth, 402 quotas, 429 rate limits, 502 inference failures. HTTP status codes, JSON error bodies, and recovery steps for the Audivra API — 401 auth, 402 quotas, 429 rate limits, 502 inference failures. | Status | Name | Meaning | Recovery | | --- | --- | --- | --- | | 400 | Bad request | Malformed JSON or missing required fields. | Fix the request body and retry | | 401 | Unauthorized | Missing, malformed, or revoked API key / session. | Mint a new key at /app/keys | | 402 | Payment required | Insufficient monthly credits, routing credits, or prepaid wallet for overages. | Upgrade at /app/billing, enable overages on Creator/Developer, or top up prepaid wallet | | 403 | Forbidden | Authenticated but not allowed for this resource. | Use a user API key for public routes | | 404 | Not found | Job, voice, avatar, or clone does not exist (or wrong owner). | Poll the job_id returned by POST /api/v1/generate | | 409 | Conflict | Resource exists but is not ready, or state prevents the operation. | Poll GET /api/voices/clone until status is ready | | 429 | Too many requests | Per-API-key rate limit exceeded. | Backoff and retry after Retry-After | | 502 | Bad gateway | Upstream inference, local worker, or API gateway unavailable. | Retry with forceCloud on generate, or route to gpu_cluster | | 503 | Service unavailable | Endpoint not configured in this deployment. | Set NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY | ## 400 Bad request Empty text, invalid plan at checkout, missing voice_id where required. **Example body:** ```json { "error": "text is required" } ``` **Recovery:** Fix the request body and retry. Validate against OpenAPI examples. ## 401 Unauthorized No Authorization header, wrong sk_live_ prefix, revoked key, or expired session. **Example body:** ```json { "error": "Unauthorized: Missing or invalid API key" } ``` **Recovery:** Mint a new key at /app/keys. Use Authorization: Bearer sk_live_… ## 402 Payment required Character/video quota exhausted on hard-cap plans; routing wallet empty on POST /api/v1/generate; voice clone blocked on free tier. **Example body:** ```json { "error": "Credit quota exceeded (12000/12000). Top up PAYG wallet at /app/billing." } ``` **Recovery:** Upgrade at /app/billing, enable overages on Creator/Developer, or top up prepaid wallet. Check limits on the limits reference page. ## 403 Forbidden Internal worker routes without x-worker-secret; admin-only surfaces; batch generate on Free Trial. **Example body:** ```json { "error": "Forbidden" } ``` **Recovery:** Use a user API key for public routes. Worker routes require WORKER_SECRET header. ## 404 Not found Unknown job_id, avatar_id, or clone UUID. **Example body:** ```json { "error": "Job not found" } ``` **Recovery:** Poll the job_id returned by POST /api/v1/generate. List voices via GET /api/v1/voices. ## 409 Conflict Voice clone still training; avatar video not completed yet. **Example body:** ```json { "error": "Voice clone still training" } ``` **Recovery:** Poll GET /api/voices/clone until status is ready. Poll GET /api/v1/jobs/{id} for video. ## 429 Too many requests More requests than the plan bucket allows in a rolling 60-second window. Paid generate/avatar/dub/batch use 100 req/min; other routes and Free Trial use 60. **Example body:** ```json { "error": "Rate limit exceeded (60 requests/minute). Retry shortly." } ``` **Recovery:** Backoff and retry after Retry-After. Use POST /api/v1/generate/batch on paid plans instead of bursting single generates. ## 502 Bad gateway INFERENCE_URL down, local worker unhealthy, Modal/RunPod webhook failed. **Example body:** ```json { "error": "Local worker failed" } ``` **Recovery:** Retry with forceCloud on generate, or route to gpu_cluster. Self-host: verify npm run inference. ## 503 Service unavailable Stripe webhooks called without STRIPE_WEBHOOK_SECRET; optional services disabled; dashboard signup on a serverless host without Supabase. **Example body:** ```json { "error": "Local JSON store is not available on this host. Set NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY." } ``` **Recovery:** Set NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY. Production refuses unpaid demo checkout; configure a live provider. --- # Limits & quotas > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/reference/limits **Section:** Reference Credits, plan caps, routing credits, rate limits, per-request text caps, and overage rules — one place for metered mobile and Global South integrations. Credits, plan caps, routing credits, rate limits, per-request text caps, and overage rules — one place for metered mobile and Global South integrations. ## Credit rates - **1 audio character = 1 credit** - **1 video second = 10 credits** - **1 STT second = 5 credits** - **1 music second = 8 credits** - **1 sound-effect clip = 20 credits** Monthly plan credits are a unified pool — TTS, video, STT, music beds, and SFX clips all draw from the same quota using the rates above. ## Routing credits (POST /api/v1/generate) - local_worker: 1 routing credit - gpu_cluster: 3 routing credits - external_api: 3 routing credits POST /api/v1/generate additionally deducts routing credits per execution node (separate from character/video metering). Default starting balance: 50 routing credits. ## Per-request caps - Max text per API request: **5,000** characters - Fast-path local routing: prompts under **500** characters (env FAST_PATH_CHAR_LIMIT) - Self-hosted Kokoro on local worker: **500** characters ## Rate limits - **60 requests/minute** per API key on standard routes (Free Trial generate bucket is also 60) - **100 requests/minute** generate bucket on paid plans for POST /api/v1/generate, /avatar, /dub, and /generate/batch - Per sk_live_ API key (hashed at enforcement) and per dashboard session. Enforced on Next.js /api/v1/* routes and the FastAPI gateway (:8080). ## Paid media scale | Plan | Media seconds | Upload | Generate rpm | Batch max | Neural lip-sync | | --- | --- | --- | --- | --- | --- | | free | 180 | 15 MB | 60 | 0 | optional | | starter | 600 | 80 MB | 100 | 50 | required | | creator | 1800 | 250 MB | 100 | 200 | required | | developer | 1800 | 500 MB | 100 | 500 | required | ## Plans | Plan | Price | Credits/mo | ~Video cap | Hard cap | PAYG | | --- | --- | --- | --- | --- | --- | | Free Trial | $0/mo | 12,000 | 1200s | At $0 wallet | $0.040/1k after quota | | Starter / Hobby | $5/mo | 36,000 | 3600s | At $0 wallet | $0.040/1k after quota | | Creator Pro | $18/mo | 145,000 | 14500s | At $0 wallet | $0.035/1k after quota | | Developer API | $79/mo | 720,000 | 72000s | At $0 wallet | $0.032/1k after quota | ## Free tier Generous free tier — top up anytime to keep building - Non-commercial license — attribution required for any public use - No custom voice cloning without a paid plan - Audio capped at 128 kbps (HD on paid tiers) - 12,000 credits/mo included — add prepaid funds to continue beyond quota ## Pay As You Go - All self-serve tiers — minimum $5 top-up · pause at $0 · no postpaid debt - Free: 12,000 credits/mo — extend with PAYG wallet at $0.04/1k - Starter: 36,000 credits/mo — PAYG at $0.04/1k after quota - Creator: 145,000 credits/mo — PAYG at $0.035/1k after quota - Developer: 720,000 credits/mo — volume PAYG at $0.032/1k Top up via `POST /api/billing/topup` or the dashboard billing page. Minimum $5. Short prompts route to local Ollama (LLM), Kokoro/Piper (TTS), and MuseTalk/Wav2Lip (lip-sync) before offloading to GPU cluster or external APIs. Every execution is logged in PostgreSQL with atomic credit deduction. --- # Changelog & API versioning > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/reference/changelog **Section:** Reference Product evolution for paying API customers — v1 stability promise, additive changes, and deprecation policy. Product evolution for paying API customers — v1 stability promise, additive changes, and deprecation policy. ## Version policy - **Current API:** v1 (/api/v1/*) - **OpenAPI info.version:** 1.0.0 - **Stability:** All routes under /api/v1/* are stable for production integrations. Breaking changes ship only under /api/v2 with a minimum 12-month v1 deprecation window. - **Additive changes:** New optional fields, endpoints, and webhook event types are additive — existing clients keep working without code changes. - **Deprecation:** Deprecated fields remain functional for at least 12 months. Sunset dates appear in this changelog and in OpenAPI operation descriptions. ## Changelog ### 1.4.20 — 2026-08-29 Studio layout no longer crashes when local RBAC roles are unseeded. **Fixed** - JSON-store Super Admin bootstrap seeds roles in the same write as the assignment - Operator emails still enter Studio if rbac_roles is empty ### 1.4.19 — 2026-08-29 Development operator is never locked out of dashboard sign-in. **Fixed** - info.commgad@gmail.com and ADMIN_EMAILS skip failed-login lockouts and the auth IP rate limit - First sign-in creates the operator account when it does not exist yet ### 1.4.18 — 2026-08-29 Local signup works without an invitation code; GET /api/me is safe while signed out. **Changed** - Non-production hosts default to open registration and automatic approval until platform settings are saved - GET /api/me returns { user: null } with 200 when there is no dashboard session **Fixed** - POST /api/auth maps signup and validation failures to 400 instead of 401 ### 1.4.17 — 2026-08-29 Development operator receives the Developer API plan. **Added** - info.commgad@gmail.com and ADMIN_EMAILS operators are granted Developer API quotas on login (Super Admin + approved studio access) ### 1.4.16 — 2026-08-29 Development operator Super Admin for info.commgad@gmail.com. **Added** - info.commgad@gmail.com is always Super Admin (studio + /admin) even when ADMIN_EMAILS is empty ### 1.4.15 — 2026-08-29 Marketing homepage and docs match Studio APIs, credit pool, and voice types. **Changed** - Homepage hero, product pillars, Studio links, and voice-type cards source HOME_PRODUCT_* / docs voice types - Architecture copy covers generate, batch, estimate, fast-path, and webhooks - Competitive generate path is POST /api/v1/generate; dub languages match the STT allowlist - Docs overview, Studio dashboard (usage/analytics/settings), quickstart credit-pool step, llms.txt pipeline ### 1.4.14 — 2026-08-29 PWA service worker no longer intercepts App Router navigations. **Changed** - Next.js request proxy lives in src/proxy.ts (middleware file convention retired). **Fixed** - /signup and other App Router pages: service worker returned a non-Response and aborted RSC - getPlatformSettings falls back to defaults when the local JSON store is unwritable - Local JSON-store accounts still sign in when Supabase Auth rejects the same email ### 1.4.13 — 2026-08-29 Signup and session auth no longer write the local JSON store on serverless hosts. **Fixed** - Dashboard signup no longer mkdir .data under /var/task on AWS Lambda - Supabase-backed createUser / authenticate / getSessionUser skip store.json dual-write - POST /api/auth returns 503 when the local store is unavailable instead of 401 ENOENT ### 1.4.12 — 2026-08-29 Admin security hardening — TOTP 2FA, login lockouts, CSRF, and security alerts. **Added** - TOTP two-factor authentication at /app/settings with backup codes - Admin /admin/security dashboard for brute-force and lockout alerts - CSRF tokens on all admin mutating API routes - Session-bound cookies — revoked sessions invalidate immediately - Configurable password policy and admin 2FA requirement in /admin/settings ### 1.4.11 — 2026-08-29 Expanded STT and dub language catalog to 35+ ISO 639-1 codes with regional TTS routing. **Added** - STT / dub allowlist: German, Italian, Dutch, Zulu, Twi, Chinese, Japanese, Korean, and more - Grouped language picker in docs try-it, STT studio, and dubbing studio - Preset voices klara-de, marco-it, lotte-nl, thando-zu with Edge-TTS routing ### 1.4.10 — 2026-08-29 Multipart generate uploads and gateway lipsync (audio_url + skip_tts). **Added** - POST /api/v1/generate accepts multipart video+audio files - Gateway /v1/video/generate skip_tts, audio_url, and sync_mode - Committed sample MP4 at public/docs-samples/example-video.mp4 ### 1.4.9 — 2026-08-29 Video+audio generate, sync_mode, media assets, JSONL batch dry_run, lipsync estimates, sample media. **Added** - POST /api/v1/generate accepts input[] (video + audio URL or asset_id) with options.sync_mode - POST /api/v1/assets CRUD and GET /api/v1/assets/{id}/file - JSONL / dry_run / batch.completed webhook on POST /api/v1/generate/batch - Estimate kind lipsync; hosted sample MP4/WAV under /api/docs/samples/ - Docs: at-a-glance table, media tips, formats, generation times ### 1.4.8 — 2026-08-29 Paid media scale: 30-minute caps, generate rate bucket, batch queue, neural lip-sync fail-closed. **Added** - POST /api/v1/generate/batch — paid queued jobs (plan max 50 / 200 / 500) - POST /api/v1/estimate — credit and cap preview **Changed** - Free Trial stays at 3 minutes / 15 MB / 60 rpm / no batch - Paid generate/avatar/dub use a 100 req/min bucket; GPU lip-sync required (no silent FFmpeg mux) ### 1.4.7 — 2026-08-29 Installable PWA with responsive shells for phone, tablet, and desktop. **Added** - Web app manifest, 192/512 icons, and /sw.js shell cache - /docs/get-started/install — add to home screen ### 1.4.6 — 2026-08-29 Pricing product rails: speech, recognition, music, and sound effects on one prepaid pool. **Added** - Homepage / billing product tabs — Text to speech, Speech to text, Music, Sound effects - Homepage playground — Play samples and Get API key - POST /api/v1/music and POST /api/v1/sfx — score beds and cues from the prepaid pool - GET /api/docs/try-preview — rate-limited hearable samples - Credit rates for music seconds and SFX clips in the usage calculator - Homepage payments grid — Stripe cards, wallets, and Checkout beside local rails ### 1.4.5 — 2026-08-29 Speech-to-text API and dubbing jobs (STT → translate → TTS → lip-sync). **Added** - POST /api/v1/stt — multipart audio or SSRF-checked audio_url, billed per second - GET /api/v1/stt — allowlisted languages and upload caps - POST /api/v1/dub — async dubbing job; poll GET /api/v1/jobs/{id} - Studio /app/stt and /app/dub - Inference POST /v1/stt (Whisper / faster-whisper) ### 1.4.4 — 2026-08-29 Launch readiness: legal pages, consent records, marketplace KYC/payouts, Supabase credit metering, and fail-closed GPU weights. **Added** - GET /legal, GET /privacy, GET /docs/legal — versioned terms, privacy, and voice consent - Consent records on signup, clone create, and marketplace publish - GET/POST /api/voices/kyc and /api/voices/payouts — seller KYC and credit payouts - GET/POST /api/admin/moderation — listing queue, KYC verify, hide reviews - GET /api/health — production readiness probe - npm test — Node test runner for billing, payouts, and legal constants **Changed** - Next.js metering writes Supabase profiles when configured - Paid marketplace listings require KYC and wait for moderation in production - Clone and remix fail closed when REQUIRE_MODEL_WEIGHTS or ENVIRONMENT=production and GPU weights are missing - Voice design builds a prompt-styled speaker then reclones; remix applies DSP then neural restyle when weights exist - Deploy docs list migrations through the latest timestamped files ### 1.4.3 — 2026-08-29 Production billing locks, avatar source SSRF, and inbound webhook hardening. **Changed** - Checkout and PAYG top-up refuse unpaid demo upgrades when the runtime is production - Paystack accepts HMAC-SHA512 only in production (shared-secret fallback is local-dev) - GET /api/docs/voice-preview is rate-limited and sends the GPU worker secret - Avatar source_url and job webhooks reject private, loopback, and metadata hosts on Next.js and the gateway **Fixed** - setPlan writes plan quotas to Supabase profiles - Signup strips initial_api_key from user_metadata after one-time delivery - profiles UPDATE cannot raise plan or credits via JWT; webhook_events and payg_topups have RLS - Gateway Stripe webhooks dedupe on event.id; WebSocket worker auth uses a timing-safe compare ### 1.4.2 — 2026-08-29 Clone rename/preview in studio, marketplace seller share, reviews, and featured ranking. **Added** - PATCH /api/voices/clone/{id} — rename a clone you own - Clone studio Preview and Rename on /app/voices - POST /api/v1/voices/community/{id}/reviews — licensed-buyer ratings - Featured marketplace sort (uses + ratings) - Seller credit share on paid listings (70% of price_credits) - SDK: renameClone, previewClone, reviewCommunityVoice, listCommunityReviews **Changed** - GET /api/v1/voices/community accepts sort=featured|popular|recent - Marketplace listings expose ratingAvg, reviewCount, and sellerEarningsCredits ### 1.4.1 — 2026-08-29 Fail-closed payment webhooks, signed sessions, marketplace metering, and outbound URL SSRF guards. **Changed** - Paystack, Flutterwave, and dLocal return 503 when the signing secret is missing — unsigned billing webhooks are rejected - Dashboard sessions are HMAC-signed; Secure cookie flag is set in production - Community voice previews require a session or API key - Outbound job/clone/design webhooks reject private, loopback, and metadata hosts **Fixed** - Marketplace per-use fees now settle on gateway TTS, Next.js gateway TTS, and stream paths - WORKER_SECRET default is refused in production for internal and GPU worker routes ### 1.4.0 — 2026-08-29 Video-first public pricing — compare matrix, Private GPU, studio grants, local-rail plan cards. **Added** - Homepage pricing surface: annual toggle, rail on every plan card, talking-head headlines - Plan compare table from PRICING_TIERS (resolution, watermark, commercial, clones, fast-path) - Studio / Team and Private GPU SKUs — seats and bring-your-own GPU, not extra volume tiers - Studio grants for African and LATAM creator studios and campus labs - /docs/concepts/pricing — FAQ and compare matrix stay in sync with the homepage ### 1.3.0 — 2026-08-29 Usage calculator for audio characters, avatar minutes, and local-rail checkout. **Added** - Pricing calculator driven from PRICING_TIERS — homepage, /app/billing, and /docs/concepts/credits - Outputs shared-credit mix as audio characters + talking-head minutes - Checkout on Pix, UPI, M-Pesa, and other local rails from the recommended plan ### 1.2.0 — 2026-08-29 Professional cloning, voice remix, and community marketplace. **Added** - Professional multi-sample cloning (kind=professional, Creator Pro+) — 5–25 files, 2–30 minutes - POST /api/v1/voices/{id}/remix — prompt-conditioned clone variants - Community marketplace — publish, browse, license, and preview listings - Studio tabs: Remix and Marketplace at /app/voices - SDK: remixVoice, listCommunityVoices, acquireCommunityVoice, publishClone **Changed** - POST /api/voices/clone accepts kind=instant|professional and larger professional sample sets - GET /api/v1/voices includes published community listings for authenticated callers - Clone training reports progress while status is training ### 1.1.0 — 2026-08-29 Voice design API, three-type docs restructure, and studio tabs. **Added** - POST /api/voices/design — prompt-based custom voices on paid plans - POST /api/voices/design/preview — sync preview before saving - Voice design studio tab at /app/voices - Docs: three voice types (preset, clone, design) with concept and API pages - SDK: createDesign, previewDesign, listDesigns, waitUntilDesignReady - Webhooks: design.ready and design.failed **Changed** - GET /api/v1/voices returns source field and designs array for authenticated callers - Custom voice slots count clones + designs together - /docs/concepts/voices redirects to /docs/overview/voices ### 1.0.0 — 2026-08-29 v1 public API stability release — unified generate, self-hosted fast-path, Global South billing. **Added** - POST /api/v1/generate — unified TTS, LLM, lip-sync, and async video in one endpoint - POST /api/v1/tts/stream — chunked Opus streaming for low-bandwidth mobile networks - Voice library docs with audio preview and copyable voice_id - Webhook reference — Stripe, Paystack, Flutterwave, dLocal payloads + idempotency - Errors & limits reference — 401/402/429/502, routing credits, plan caps - Rate limiting enforced on Next.js /api/v1/* (60 req/min per API key) - GET /api/v1/changelog — machine-readable release history and v1 policy - X-Audivra-Api-Version: 1 response header on all /api/v1/* routes - Air-gapped deployment mode (AIR_GAPPED / DEPLOYMENT_MODE=air_gapped) - Thin TypeScript + Python SDKs (sdk/typescript, sdk/python) - Voice clone API-key auth, DELETE, multi-sample upload, clone.ready webhooks - Guides, docs search (⌘K), and try-it playgrounds on TTS + generate pages **Changed** - 402 returned when API key is valid but credit wallet is exhausted (was 401) - Video seconds quota enforced before async job creation ### 0.9.0 — 2026-08-15 Beta — async avatar jobs, voice cloning, processing-node routing. **Added** - POST /api/v1/avatar — async lip-synced MP4 jobs with SSE status stream - Voice cloning (F5-TTS / XTTS) on Starter+ plans - Fast-path routing — local_worker, gpu_cluster, external_api with routing credits - Global South checkout — Paystack, Flutterwave, dLocal alongside Stripe - Self-hosted local worker (Ollama + Kokoro + MuseTalk on :11435) ### 0.8.0 — 2026-07-01 Early access — TTS API, dashboard, and metering foundation. **Added** - POST /api/v1/tts — WAV output with Kokoro and XTTS engines - Audivra Studio dashboard — playground, keys, billing, usage - Credit metering — 1 character = 1 credit, 1 video second = 10 credits - OpenAPI 3.0 spec and Postman collection export --- # Legal > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/legal **Section:** Reference Terms, privacy, and voice-consent policy (version 2026-08-29). Version 2026-08-29 · effective 29 August 2026. ## Terms of Service Audivra provides voice and avatar APIs. You must have rights to any voice or face you upload. Paid usage is billed in credits. We may suspend accounts that violate these terms. ### Accounts and keys You are responsible for API keys issued to your account. Do not share sk_live_ secrets. We may revoke keys that leak or abuse rate limits. ### Credits and refunds Plan credits reset each billing cycle. PAYG wallet top-ups are prepaid. Failed GPU jobs are refunded automatically when the worker reports failure. Chargebacks may suspend the account. ### Acceptable use No impersonation of a living person without written permission, no CSAM, no fraud, and no attempts to bypass safety or billing. We may refuse or delete violating content. ### Voice and likeness rights You warrant that every clone, remix, design, or marketplace listing is a voice you recorded or for which you hold written permission. Marketplace sellers keep 70% of per-use listing credits. ## Privacy We store account email, usage events, uploaded voice samples, and job outputs needed to run the service. We do not sell personal data. ### What we store Profiles, hashed API keys, credit balances, audio samples for clones, generated media, marketplace listings, consent records, and payment-provider customer IDs. ### Processors Supabase (auth and database), Stripe / Paystack / Flutterwave / dLocal (payments), and optional GPU hosts (Modal or RunPod) process data to fulfill requests. ### Retention Delete a clone to remove its samples. Closing an account retains billing records as required by law. Consent records are kept for audit. ### Contact Privacy requests: use the dashboard Settings page or email the address on your invoice. ## Voice consent Cloning another person’s voice without permission is prohibited. Each clone and marketplace listing records the legal version you accepted and the time of acceptance. ### Who may be cloned Only your own recorded speech, or a speaker who gave you written permission. Do not upload copyrighted performances or celebrity impressions sold as the original person. ### Marketplace Paid listings require KYC (legal name and country). First paid publish waits for moderation. Reviews can be hidden by operators. Sellers request payouts from earned credits. ### Record we keep We store consent version, timestamp, and optional IP/user-agent on signup, clone create, and listing publish. That record is the compliance log — a checkbox alone is not enough. --- # Enterprise & private deployment > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/self-hosted/enterprise **Section:** Self-hosted Air-gapped inference, on-prem GPU clusters, SLA-backed uptime, and VPC isolation — for teams that need voice + avatar APIs inside their own perimeter. Air-gapped inference, on-prem GPU clusters, SLA-backed uptime, and VPC isolation — for teams that need voice + avatar APIs inside their own perimeter. ## SLA tiers - **Standard (cloud SaaS)** — 99.5% monthly · Email · docs · community. Shared multi-tenant — audivra.dev or your custom domain - **Enterprise (private cloud)** — 99.9% monthly · Dedicated channel · onboarding · quarterly review. Single-tenant VPC, optional air-gapped inference tier - **Air-gapped (on-prem)** — Customer-operated · Runbook + remote break-glass (optional). No outbound internet from inference tier; license key offline validation ## Deployment models ### Private VPC (recommended B2B) Audivra SaaS + gateway in your AWS/Azure/GCP VPC. Postgres (Supabase self-hosted or RDS), Redis, and S3-compatible storage stay inside the account. Modal/RunPod GPU calls optional or replaced with on-prem nodes. - Deploy docker-compose.prod or K8s helm chart in private subnet - Restrict ingress to corporate VPN or Zero Trust proxy - Use customer-managed KMS for S3 and database encryption - Route /api/v1/* through internal ALB — no public dashboard unless required ### On-prem GPU cluster Dedicated RTX/A100 nodes run inference/main.py and local_worker.py. Fast-path routing sends short prompts to local Kokoro/Ollama; heavy lip-sync stays on-cluster MuseTalk workers. - Minimum: 1× RTX 4090 (24 GB) for MuseTalk + Kokoro concurrent load - Scale: Celery worker pool bound to GPU count — one video job per GPU slot - Set PREFERRED_NODE=local_worker and disable external_api in routing profile - Monitor queue depth via Redis + /app/admin (or Prometheus exporter) ### Air-gapped / offline Inference tier has no egress. Model weights and voice assets ship on signed media; billing and admin UI run on a separate connected zone or entirely offline with manual license files. - Set AIR_GAPPED=true or DEPLOYMENT_MODE=air_gapped in .env - npm run inference:bootstrap on a connected staging machine, then transfer artifacts - Disable Modal, RunPod, Stripe, and external TTS fallbacks in env - Use WORKER_SECRET for worker-to-gateway auth only - Audit webhook and payment routes — disable if not applicable offline ## Security controls - **API keys:** SHA-256 hashed at rest; rotate via /app/keys or admin API - **Data residency:** Self-host Postgres + S3 in your region; no cross-border inference by default - **SSO / SAML:** Entra ID, Okta, or Google Workspace via Supabase Auth (enterprise config) - **Admin audit:** /app/admin usage console; webhook_events + job_ledger tables for billing disputes - **Rate limits:** 60 req/min per key — tunable per tenant in private deployments Contact: enterprise@audivra.dev — Include expected monthly characters, video minutes, GPU footprint, and compliance requirements (SOC 2, HIPAA BAA, etc.). --- # Webhooks > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/webhooks **Section:** API reference Payment provider webhooks — payload schemas, signature headers, retries, and idempotency. Inbound payment webhooks upgrade plans and prepaid credits. Outbound job webhooks fire on video.completed and video.failed. Idempotency & duplicate deliveries Audivra persists inbound payment webhook keys in webhook_events (Supabase) or .data/store.json (dev). Duplicate Stripe event.id, Paystack reference, Flutterwave tx_ref, or dLocal payment id returns HTTP 200 with { "duplicate": true } without re-processing. Job webhooks fire at most once per terminal event (video.completed or video.failed) — tracked on video_jobs.webhook_notified_event. Clone webhooks (clone.ready / clone.failed) fire at most once per clone — tracked on voice_clones.webhook_notified_event. Retry behavior **Inbound:** Stripe, Paystack, Flutterwave, and dLocal retry failed deliveries (non-2xx or timeout) with exponential backoff for up to several days. Return 200 only after your handler succeeds. Audivra returns 400/401 for invalid signatures and 503 when the provider signing secret is missing — unsigned payment webhooks are never accepted. **Outbound:** Celery workers POST job webhooks once — 30s timeout on success, 15s on failure. Failed delivery is logged; there is no automatic retry from Audivra. Use GET /api/v1/jobs/{id} or SSE /api/v1/jobs/{id}/events as a reliable fallback. Voice clone webhooks (clone.ready / clone.failed) follow the same delivery semantics. ## Stripe — POST /api/webhooks/stripe **Env vars:** - `STRIPE_SECRET_KEY` — Stripe API secret — required to construct events. - `STRIPE_WEBHOOK_SECRET` — Signing secret from Stripe Dashboard → Webhooks → endpoint. **Signature headers:** - `stripe-signature` (required) — HMAC-SHA256 timestamped signature. Verified with stripe.webhooks.constructEvent(). Raw request body must be passed verbatim to constructEvent — do not parse JSON before verification. Missing or invalid signatures return 400. ### checkout.session.completed User finished Stripe Checkout for a subscription plan. **Audivra action:** Sets user plan from metadata.plan (starter · creator · developer). Persists stripeCustomerId on the profile. ```json { "id": "evt_…", "type": "checkout.session.completed", "data": { "object": { "id": "cs_…", "customer": "cus_…", "metadata": { "audivra_user_id": "usr_…", "plan": "creator" } } } } ``` ### invoice.paid Subscription invoice paid — monthly renewal. **Audivra action:** Resets billing cycle counters for the Stripe customer. If profile was free or suspended, upgrades to creator. ```json { "id": "evt_…", "type": "invoice.paid", "data": { "object": { "id": "in_…", "customer": "cus_…", "amount_paid": 2900 } } } ``` ### invoice.payment_failed Subscription renewal charge failed. **Audivra action:** Sets plan to suspended — reduced character and video quotas until payment succeeds. ```json { "id": "evt_…", "type": "invoice.payment_failed", "data": { "object": { "customer": "cus_…" } } } ``` ### customer.subscription.updated Subscription status or metadata changed. **Audivra action:** Maps status → plan: active uses metadata.plan; canceled/unpaid → free; past_due/incomplete → suspended. ```json { "id": "evt_…", "type": "customer.subscription.updated", "data": { "object": { "customer": "cus_…", "status": "active", "metadata": { "plan": "developer" } } } } ``` ### customer.subscription.deleted Subscription canceled or expired. **Audivra action:** Downgrades matching profile to free tier. ```json { "id": "evt_…", "type": "customer.subscription.deleted", "data": { "object": { "customer": "cus_…" } } } ``` ### payment_intent.succeeded One-time prepaid credit top-up (PaymentIntent). **Audivra action:** Adds amount_received (cents) to creditBalanceCents for the receipt email. ```json { "id": "evt_…", "type": "payment_intent.succeeded", "data": { "object": { "amount_received": 5000, "receipt_email": "user@example.com", "metadata": { "audivra_user_email": "user@example.com" } } } } ``` **Success response:** ```json { "received": true } ``` ## Paystack — POST /api/webhooks/paystack **Env vars:** - `PAYSTACK_SECRET_KEY` — Paystack secret key for API calls. - `PAYSTACK_WEBHOOK_SECRET` — Shared secret compared against inbound signature header. **Signature headers:** - `x-paystack-signature` — Primary header — compared to PAYSTACK_WEBHOOK_SECRET when set. - `authorization` — Fallback header if x-paystack-signature is absent. HMAC-SHA512 of the raw request body using PAYSTACK_SECRET_KEY, compared to x-paystack-signature (timing-safe). Production accepts HMAC only. PAYSTACK_WEBHOOK_SECRET shared-secret comparison is local-dev fallback. Non charge.success events return 200 with ignored: true. ### charge.success Successful charge — M-Pesa, card, or bank transfer via Paystack. **Audivra action:** Resolves customer email → profile. Applies data.plan when present. Adds data.amount / 100 to credit balance (Paystack amounts are in kobo). ```json { "event": "charge.success", "data": { "reference": "T123456789", "amount": 290000, "currency": "KES", "customer": { "email": "user@example.com" }, "plan": "creator" } } ``` **Success response:** ```json { "received": true, "reference": "T123456789" } ``` ## Flutterwave — POST /api/webhooks/flutterwave **Env vars:** - `FLUTTERWAVE_SECRET_KEY` — Flutterwave secret key for API calls. - `FLUTTERWAVE_WEBHOOK_SECRET` — Secret hash configured in Flutterwave dashboard — sent as verif-hash. **Signature headers:** - `verif-hash` (required) — Must equal FLUTTERWAVE_WEBHOOK_SECRET when that env var is set. Compare verif-hash header to FLUTTERWAVE_WEBHOOK_SECRET. Returns 401 when configured and mismatched. ### charge.completed Successful Flutterwave charge (card, M-Pesa, MTN, etc.). **Audivra action:** Maps data.customer.email → profile. Applies data.plan when present. Credits: data.amount × 100 (major currency units → cents). ```json { "event": "charge.completed", "data": { "tx_ref": "audivra-creator-abc123", "amount": 29, "currency": "USD", "customer": { "email": "user@example.com" }, "plan": "creator" } } ``` **Success response:** ```json { "received": true, "reference": "audivra-creator-abc123" } ``` ## dLocal — POST /api/webhooks/dlocal **Env vars:** - `DLOCAL_API_KEY` — dLocal API key. - `DLOCAL_SECRET_KEY` — dLocal secret for signing API requests. - `DLOCAL_WEBHOOK_SECRET` — Shared secret for inbound webhook verification. **Signature headers:** - `x-dlocal-signature` — Primary signature header — compared to DLOCAL_WEBHOOK_SECRET. - `authorization` — Fallback when x-dlocal-signature is absent. When DLOCAL_WEBHOOK_SECRET is set, header must match exactly. Returns 401 on mismatch. ### payment.approved Payment approved — Pix, UPI, Mobile Money, bank transfer, etc. **Audivra action:** Maps payer.email → profile. Applies plan when present. Credits: amount × 100 (major units → cents). ```json { "id": "PAY-123456789", "status": "PAID", "amount": 29.0, "currency": "BRL", "payer": { "email": "user@example.com" }, "plan": "starter" } ``` **Success response:** ```json { "received": true, "reference": "PAY-123456789" } ``` ## Job completion webhooks (outbound) Audivra POSTs to your URL when async avatar/video jobs reach a terminal state. Configure a default in the dashboard or override per request. Outbound URLs must be HTTPS in production; private, loopback, and cloud-metadata hosts are rejected (SSRF protection). ### video.completed GPU pipeline finished — MP4 available. ```json { "event": "video.completed", "job_id": "abc123def456", "status": "completed", "output_url": "https://cdn.example.com/renders/abc123.mp4", "duration_seconds": 12 } ``` ### video.failed Pipeline failed after retries or quota error. ```json { "event": "video.failed", "job_id": "abc123def456", "status": "failed", "error": "Inference engine unavailable (502).", "refunded_cents": 120 } ``` ### batch.completed All jobs in a generate batch reached completed or failed. ```json { "event": "batch.completed", "id": "batch_abc", "status": "COMPLETED", "metrics": { "totalGenerations": 20, "successCount": 19, "failedCount": 1, "pendingCount": 0 } } ``` ## Voice clone webhooks (outbound) Audivra POSTs to your URL when a voice clone reaches ready or failed. Pass webhook_url on POST /api/voices/clone or rely on the dashboard default from PATCH /api/settings. ### clone.ready GPU speaker prep finished — pass voice_id in TTS and generate. ```json { "event": "clone.ready", "clone_id": "3f2c9a1e-…", "voice_id": "3f2c9a1e-…", "status": "ready", "name": "Founder voice", "engine": "f5-tts" } ``` ### clone.failed Training failed — slot remains consumed until you DELETE the clone. ```json { "event": "clone.failed", "clone_id": "3f2c9a1e-…", "voice_id": "3f2c9a1e-…", "status": "failed", "error": "Sample is too short — upload 5–10 seconds of clean speech." } ``` ## Voice design webhooks (outbound) Audivra POSTs to your URL when a voice design reaches ready or failed. Pass webhook_url on POST /api/voices/design or rely on the dashboard default from PATCH /api/settings. ### design.ready Speaker reference generated — pass voice_id in TTS and generate. ```json { "event": "design.ready", "design_id": "8a1b2c3d-…", "voice_id": "8a1b2c3d-…", "status": "ready", "name": "Product narrator", "engine": "f5-tts", "prompt": "Warm Kenyan English female narrator…" } ``` ### design.failed Generation failed — slot remains consumed until you DELETE the design. ```json { "event": "design.failed", "design_id": "8a1b2c3d-…", "voice_id": "8a1b2c3d-…", "status": "failed", "error": "Voice design produced no speaker reference" } ``` --- # Billing > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/api/billing **Section:** API reference Upgrade plans via Stripe or Global South payment rails. ### POST /api/billing/checkout Initiate plan checkout. Returns Stripe session URL or provider redirect. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `plan` | string | yes | free · starter · creator · developer | | `provider` | string | no | dlocal · paystack · flutterwave · ebanx · yellowcard · stripe | | `region` | string | no | africa · latam · south-asia | **Request body:** ```json { "plan": "creator", "provider": "paystack", "region": "africa" } ``` ### POST /api/billing/topup Prepaid PAYG wallet top-up. Minimum $5. **Auth:** Bearer API key required | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `amountUsd` | number | yes | USD amount | | `provider` | string | no | stripe · dlocal · paystack · … | **Request body:** ```json { "amountUsd": 20, "provider": "stripe" } ``` ### PUT /api/billing/payg-settings Update auto top-up threshold and recharge amount. **Auth:** Bearer API key required **Request body:** ```json { "autoTopUpEnabled": true, "autoTopUpAmountCents": 2000, "lowBalanceThresholdCents": 1000 } ``` ## Plans | plan | Price | Credits/mo | | --- | --- | --- | | free | $0/mo | 12,000 | | starter | $5/mo | 36,000 | | creator | $18/mo | 145,000 | | developer | $79/mo | 720,000 | ## Payment providers | Market | Provider | Local rails | | --- | --- | --- | | All Global South (single API) | dLocal | Pix, UPI, Mobile Money, local cards, bank transfers | | Africa-first (creators & devs) | Paystack or Flutterwave | M-Pesa, MTN, Airtel, USSD, NGN/KES direct debit | | Latin America | EBANX | Pix (Brazil), OXXO (Mexico), PSE (Colombia) | | Low FX cost / Web3 native | Yellow Card / USDC | USDT/USDC via local Mobile Money ramps | | Cards / US-EU / diaspora | Stripe | Cards, Apple Pay, Google Pay, Link, SEPA, Checkout subscriptions | --- # Guides > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides **Section:** Guides Step-by-step tutorials for creators, developers, and self-hosters — reference tells what; guides tell how. Narrative tutorials — reference tells what; guides tell how. | Guide | Audience | Duration | Path | | --- | --- | --- | --- | | First talking avatar in 5 minutes | Creators | ~5 min | /docs/guides/first-talking-avatar | | Dub a talking head | Creators | ~8 min | /docs/guides/dub-talking-head | | Stream Opus TTS on low bandwidth | Developers | ~10 min | /docs/guides/stream-opus-low-bandwidth | | Self-host on an RTX 4090 | Self-hosters | ~30 min | /docs/guides/self-host-rtx-4090 | | Accept M-Pesa via Paystack webhook | Developers | ~20 min | /docs/guides/paystack-mpesa-webhook | | Professional voice clone | Creators | ~15 min | /docs/guides/professional-voice-clone | | Share a community voice | Creators | ~10 min | /docs/guides/share-community-voice | | Media content tips | Creators | ~4 min | /docs/guides/media-tips | | Media formats | Developers | ~3 min | /docs/guides/media-formats | | Generation times | Developers | ~3 min | /docs/guides/generation-times | --- # First talking avatar in 5 minutes > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/first-talking-avatar **Section:** Guides Create a lip-synced talking-head video from text — dashboard or API — and download the MP4 when the job completes. **Audience:** Creators · **Duration:** ~5 min **Outcome:** A completed MP4 talking avatar you can share or embed in your product. ## Step 1: Create an account and open the playground Sign up at /signup — you receive 12,000 free credits (~20 minutes of audio or ~20 minutes of video at typical rates). Open the Avatars studio at /app/avatars or use the playground at /app/playground to test without writing code. ## Step 2: Pick a voice and avatar preset Choose voice_id aurora (English studio) or zuri-sw (Swahili regional) from the voice library. Choose avatar_id studio-host for a photo-based presenter or sales-closer for MuseTalk lip-sync over video reference. See the full preset list on the Avatars concept page if you need regional voices or expressive models. ## Step 3: Submit your script Paste 1–3 sentences (under 500 characters keeps fast-path routing cheap). Example: “Welcome to our product launch — Audivra turns text into talking video in seconds.” Click Generate. GPU rendering takes 2–30 seconds; the dashboard shows SSE progress (TTS → lip-sync → render). ## Step 4: Download or poll via API When status is completed, download the MP4 from the dashboard or use the API flow below for automation. ``` curl -X POST https://audivra.dev/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Welcome to our launch.","voice_id":"aurora","avatar_id":"studio-host"}' # → { "job_id": "…", "status": "PROCESSING", "poll": "/api/v1/jobs/…" } curl https://audivra.dev/api/v1/jobs/{job_id} \ -H "Authorization: Bearer sk_live_…" # When completed → download_url or GET /api/v1/avatar/{job_id}/video ``` ## Step 5: Upgrade when you ship commercially Free tier videos are watermarked and non-commercial. Starter ($5/mo) removes the watermark and unlocks 720p output. Creator Pro ($18/mo) adds 1080p, voice cloning, and prepaid PAYG top-ups for production traffic. > 1 video second = 10 credits. Top up from $5 when you exceed your monthly quota. ## Related reference - Avatars & jobs API: /docs/api/avatars - Credits: /docs/concepts/credits - Dashboard guide: /docs/get-started/dashboard --- # Dub a talking head > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/dub-talking-head **Section:** Guides Upload source speech, translate into a target language, and lip-sync a talking-head with a catalog voice. **Audience:** Creators · **Duration:** ~8 min **Outcome:** An MP4 whose lips follow a translated track generated from your source audio. ## Step 1: Open the dubbing studio Sign in and go to /app/dub. The same pipeline is POST /api/v1/dub with a multipart source file. Use audio-only if you only need a new talking-head, or MP4/WebM if you want the original face as the lip-sync reference. ## Step 2: Choose language and voice target_language is allowlisted (German, Italian, Dutch, Swahili, Zulu, Twi, Hindi, and 30+ more). Pick a voice_id that matches the target language when possible. If speech recognition is not installed on the worker, paste a script to skip STT and still run translate + TTS + lip-sync. ## Step 3: Submit and poll The response is 202 with job_id. Poll GET /api/v1/jobs/{id} until completed, then download the MP4. ``` curl -X POST https://audivra.dev/api/v1/dub \ -H "Authorization: Bearer sk_live_…" \ -F "source=@clip.mp4" \ -F "target_language=sw" \ -F "voice_id=zuri-sw" curl https://audivra.dev/api/v1/jobs/{job_id} \ -H "Authorization: Bearer sk_live_…" ``` > STT bills 5 credits per second. TTS and video still bill characters and 10 credits per video second. ## Related reference - Speech to text API: /docs/api/stt - Dubbing API: /docs/api/dub - Avatars & jobs: /docs/api/avatars --- # Stream Opus TTS on low bandwidth > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/stream-opus-low-bandwidth **Section:** Guides Deliver chunked Opus audio for mobile networks in the Global South — 48 kbps streams instead of multi-megabyte WAV files. **Audience:** Developers · **Duration:** ~10 min **Outcome:** A streaming Opus pipeline your mobile app or IVR can play incrementally on 2G/3G links. ## Step 1: Why Opus instead of WAV WAV responses from POST /api/v1/tts can be 500 KB+ for a short sentence — painful on M-Pesa-tier mobile data. POST /api/v1/tts/stream returns chunked Opus (or AAC) optimized for Global South bandwidth. Typical footprint: ~48 kbps. Use voice_id zuri-sw, umar-ha, or swara-hi for regional African languages on Kokoro-82M. ## Step 2: Request a streaming response Set format to opus (default) or aac. The response uses Transfer-Encoding: chunked — read chunks as they arrive. ``` curl -X POST https://audivra.dev/api/v1/tts/stream \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Habari. Karibu kwenye huduma yetu.","voice_id":"zuri-sw","format":"opus"}' \ --output stream.opus ``` ## Step 3: Play in the browser or mobile app Opus chunks can be fed to MediaSource Extensions (web) or an Opus decoder on Android/iOS. For quick validation, pipe to ffplay: ffplay -autoexit stream.opus ``` const res = await fetch("https://audivra.dev/api/v1/tts/stream", { method: "POST", headers: { Authorization: "Bearer sk_live_…", "Content-Type": "application/json", }, body: JSON.stringify({ text: "Sentence one. Sentence two.", voice_id: "zuri-sw", format: "opus", }), }); const reader = res.body?.getReader(); // Append chunks to MediaSource or buffer for native Opus decode ``` ## Step 4: Tune for your network Keep sentences under 500 characters for fast-path local routing (1 credit) when a local worker is configured. Set DEFAULT_STREAM_FORMAT=opus in your deployment env for server-side defaults. Monitor X-Characters and X-Stream-Format response headers for billing and debugging. > 1 audio character = 1 credit. Streaming and sync TTS meter the same way. ## Related reference - Text to speech API: /docs/api/tts - Voices reference: /docs/overview/voices - Processing nodes: /docs/concepts/processing-nodes --- # Self-host on an RTX 4090 > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/self-host-rtx-4090 **Section:** Guides Run Ollama, Kokoro-82M, and MuseTalk on a local RTX 4090 — route short prompts on-box before cloud GPU offload. **Audience:** Self-hosters · **Duration:** ~30 min **Outcome:** A local inference stack on :8090 / :11435 that handles TTS and lip-sync under ~500 characters without cloud credits. ## Step 1: Hardware and VRAM budget RTX 4090 (24 GB VRAM) comfortably runs MuseTalk lip-sync (~4 GB), Kokoro TTS (~500 MB), and Ollama qwen2.5:3b (~2.5 GB) concurrently. RTX 3060 (12 GB) works for TTS-only or sequential jobs — avoid parallel MuseTalk + large LLM on 8 GB cards. ## Step 2: Install dependencies Clone the repo, copy .env.example to .env, and install Python inference deps plus Ollama. ``` git clone https://github.com/your-org/audivra.git && cd audivra cp .env.example .env # LLM for fast-path (<500 chars) ollama pull qwen2.5:3b # Python inference (Kokoro + MuseTalk) pip install -r inference/requirements.txt npm run inference:bootstrap ``` ## Step 3: Start local services Run inference on :8090 (TTS + lip-sync) and the local worker gateway on :11435 (routes Ollama + Kokoro before cloud). ``` # Terminal 1 — GPU pipeline npm run inference # :8090 # Terminal 2 — fast-path gateway npm run local-worker # :11435 ``` ## Step 4: Wire Audivra to your local stack Point the Next.js app or gateway at your local worker. Short prompts route locally; longer scripts offload to Modal/cloud. ``` OLLAMA_URL=http://127.0.0.1:11434 LOCAL_WORKER_GATEWAY_URL=http://127.0.0.1:11435 INFERENCE_URL=http://127.0.0.1:8090 FAST_PATH_CHAR_LIMIT=500 LOCAL_VRAM_THRESHOLD_GB=6 ``` ## Step 5: Smoke-test the fast path Send a short TTS request through the unified generate endpoint — meta.executedBy should return local_worker with 1 routing credit. ``` curl -X POST http://localhost:3000/api/v1/generate \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"text":"Hello from my RTX 4090.","taskType":"tts","voice_id":"aurora"}' ``` > Lip-sync video jobs over ~200 characters still route to gpu_cluster even on a healthy local worker. ## Related reference - Local worker reference: /docs/self-hosted/local-worker - Deploy to production: /docs/self-hosted/deploy - Processing nodes: /docs/concepts/processing-nodes --- # Accept M-Pesa via Paystack webhook > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/paystack-mpesa-webhook **Section:** Guides Let Kenyan users pay with M-Pesa through Paystack — checkout redirect, webhook verification, and plan upgrade on charge.success. **Audience:** Developers · **Duration:** ~20 min **Outcome:** Live M-Pesa checkout that upgrades the user plan when Paystack fires charge.success to your webhook. ## Step 1: Create a Paystack account and keys Register at Paystack and enable Kenya (KES) collections including Mobile Money / M-Pesa. Copy your secret key and set PAYSTACK_SECRET_KEY in .env. Generate a webhook secret for PAYSTACK_WEBHOOK_SECRET. ## Step 2: Start checkout from your app Call POST /api/billing/checkout with provider paystack and region africa. The user is redirected to Paystack’s hosted page where they choose M-Pesa. ``` curl -X POST https://audivra.dev/api/billing/checkout \ -H "Cookie: session=…" \ -H "Content-Type: application/json" \ -d '{"plan":"creator","provider":"paystack","region":"africa"}' # → { "ok": true, "url": "https://checkout.paystack.com/…", "mode": "redirect" } ``` ## Step 3: Expose your webhook URL In Paystack Dashboard → Settings → Webhooks, set URL to https://your-domain.com/api/webhooks/paystack. Subscribe to charge.success. For local dev, use ngrok or Cloudflare Tunnel to forward HTTPS to localhost:3000. ``` https://audivra.dev/api/webhooks/paystack ``` ## Step 4: Verify signatures in production Audivra verifies x-paystack-signature as HMAC-SHA512 of the raw body using PAYSTACK_SECRET_KEY. Production accepts HMAC only; PAYSTACK_WEBHOOK_SECRET shared-secret comparison is a local-dev fallback. On charge.success, the handler dedupes by data.reference, maps customer email → profile, and applies the purchased plan. ``` PAYSTACK_SECRET_KEY=sk_live_… PAYSTACK_WEBHOOK_SECRET=whsec_… DEFAULT_PAYMENT_PROVIDER=paystack ``` ## Step 5: Confirm the upgrade After a test M-Pesa payment, check /app/billing — credits and plan tier should update within seconds. Use Paystack test mode first; switch to live keys only after end-to-end verification. > Flutterwave is an alternative for pan-African M-Pesa + MTN rails — see the Billing API for provider options. ## Related reference - Billing API: /docs/api/billing - Webhooks reference: /docs/api/webhooks - Credits & plans: /docs/concepts/credits --- # Professional voice clone > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/professional-voice-clone **Section:** Guides Train a higher-quality clone from 5–25 samples covering 2–30 minutes of speech. **Audience:** Creators · **Duration:** ~15 min **Outcome:** A professional clone voice_id ready for TTS and talking avatars. ## Step 1: Upgrade to Creator Pro Professional cloning is available on Creator Pro and Developer. Starter plans can still create instant clones from 1–5 short samples. ## Step 2: Record clean speech Capture 5–25 files of the same speaker in a quiet room. Aim for 2–30 minutes total. Avoid music and overlapping voices. ## Step 3: Upload from the studio or API In /app/voices open Cloned voices and use Professional clone, or POST /api/voices/clone with kind=professional and multiple samples fields. ``` curl -X POST https://audivra.dev/api/voices/clone \ -H "Authorization: Bearer sk_live_…" \ -F "name=Studio voice" \ -F "kind=professional" \ -F "consent=true" \ -F "engine=f5-tts" \ -F "samples=@take1.wav" \ -F "samples=@take2.wav" \ -F "samples=@take3.wav" \ -F "samples=@take4.wav" \ -F "samples=@take5.wav" ``` ## Step 4: Wait for ready, then synthesize Poll GET /api/voices/clone until status is ready (or handle clone.ready). Pass the UUID as voice_id to POST /api/v1/tts. ## Related reference - Voice cloning API: /docs/api/voice-cloning - Cloned voices: /docs/concepts/cloned-voices - Voice remix: /docs/api/voice-remix --- # Share a community voice > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/share-community-voice **Section:** Guides Publish a ready clone to the marketplace and let others use the listing as voice_id. **Audience:** Creators · **Duration:** ~10 min **Outcome:** A published listing others can preview, license, and use in TTS. ## Step 1: Train a ready clone you have permission to share Only publish voices you recorded or have written permission to share. Instant or professional clones both work once status is ready. ## Step 2: Publish with consent In /app/voices open Marketplace, or POST /api/voices/clone/{id}/publish with consent: true. That stores a consent record. Paid listings need KYC first; in production they stay pending until an admin approves. You keep 70% of price_credits. ``` curl -X POST https://audivra.dev/api/voices/clone/{id}/publish \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"title":"Warm narrator","tags":["narration"],"price_credits":0,"consent":true}' ``` ## Step 3: Others license and synthesize Browse GET /api/v1/voices/community (sort=featured by default). POST /api/v1/voices/community/{listing_id} to license, then pass the listing UUID as voice_id. Licensed buyers can rate the listing. ## Related reference - Marketplace API: /docs/api/marketplace - Community marketplace: /docs/concepts/marketplace - Voice cloning: /docs/api/voice-cloning --- # Media content tips > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/media-tips **Section:** Guides Prepare video and audio so lip-sync looks natural — faces, noise, and duration mismatch. **Audience:** Creators · **Duration:** ~4 min **Outcome:** Inputs that MuseTalk and LivePortrait can actually lock onto. ## Step 1: Frame the face Use a front-facing or slight three-quarter shot. Full profile, heavy occlusion, or tiny faces reduce lip accuracy. If you generate the source with an image-to-video model, include “the character should be speaking naturally” so the mouth is already moving. ## Step 2: Keep audio clean Prefer a single speaker with little music or room noise. Overlapping speech confuses both STT and lip-sync. ## Step 3: Match duration with sync_mode When the clip and the track differ in length, pass options.sync_mode: cut_off (shorter wins), loop or bounce (repeat video to cover audio), silence (pad audio), or remap (time-stretch video). Studio-style default: bounce when audio is longer; cut_off when video is longer. ## Related reference - Media formats: /docs/guides/media-formats - Generate API: /docs/api/generate - Generation times: /docs/guides/generation-times --- # Media formats > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/media-formats **Section:** Guides Supported containers, how to pass URL vs upload vs asset_id, and plan size caps. **Audience:** Developers · **Duration:** ~3 min **Outcome:** A valid generate or asset request that passes sniffing. ## Step 1: Containers Video: MP4 or WebM. Audio: WAV, MP3, M4A, OGG, FLAC, or WebM. Images (assets / avatar source): JPEG, PNG, WebP. Magic-byte sniffing rejects truncated files. Minimum ~100 bytes; maximum is the plan mediaBytes cap (15 MB free, up to 500 MB on Developer). ## Step 2: Three input modes Public URL (SSRF-checked https), multipart upload, or asset_id from POST /api/v1/assets. Sample files for first-call testing: GET /api/docs/samples/example-video.mp4 and GET /api/docs/samples/example-audio.wav. ## Related reference - Assets API: /docs/api/assets - Media tips: /docs/guides/media-tips --- # Generation times > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/guides/generation-times **Section:** Guides What to expect from async lipsync jobs and how to poll or wait on webhooks. **Audience:** Developers · **Duration:** ~3 min **Outcome:** A client that does not time out waiting on GPU render. ## Step 1: Typical latency Text-to-avatar jobs usually finish in 2–30 seconds depending on script length. Video+audio lipsync tracks source duration plus model overhead. The API returns 202 with job_id immediately. Poll GET /api/v1/jobs/{id} until status is completed or failed, or subscribe to video.completed webhooks. ## Step 2: If a job looks stuck queued or lipsync for several minutes usually means the inference worker is down (start :8090) or Redis workers are not consuming. Paid plans fail closed if neural lip-sync is unavailable — they do not silently mux FFmpeg. ## Related reference - Jobs API: /docs/api/avatars - Webhooks: /docs/api/webhooks --- # Local worker > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/self-hosted/local-worker **Section:** Self-hosted Self-hosted stack — Ollama, Kokoro-82M, MuseTalk on RTX 3060/4090 or CPU. Short prompts route to local Ollama (LLM), Kokoro/Piper (TTS), and MuseTalk/Wav2Lip (lip-sync) before offloading to GPU cluster or external APIs. Every execution is logged in PostgreSQL with atomic credit deduction. ## Stack - **Fast LLM:** Ollama — qwen2.5:3b / llama3.2:3b (~2.5 GB VRAM/RAM) - **TTS:** Kokoro-82M or Piper TTS (~500 MB RAM / CPU-friendly) - **Lip-sync video:** MuseTalk or Wav2Lip (~4 GB VRAM) ```bash ollama pull llama3.2:3b pip install -r inference/requirements.txt npm run inference # :8090 npm run local-worker # :11435 ``` ```env OLLAMA_URL=http://127.0.0.1:11434 LOCAL_WORKER_GATEWAY_URL=http://127.0.0.1:11435 INFERENCE_URL=http://127.0.0.1:8090 FAST_PATH_CHAR_LIMIT=500 LOCAL_VRAM_THRESHOLD_GB=6 ``` --- # Deploy > This is a page from the Audivra documentation. For a complete page index, fetch http://127.0.0.1:3000/docs/llms.txt. For the full documentation in a single file, fetch http://127.0.0.1:3000/docs/llms-full.txt. **URL:** http://127.0.0.1:3000/docs/self-hosted/deploy **Section:** Self-hosted Production deployment with Supabase, Docker Compose, Caddy TLS, and Celery workers. | Layer | Detail | | --- | --- | | SaaS (Next.js) | Studio, playground, STT, dub, voices, agents, keys, billing | | Gateway (FastAPI :8080) | Auth, rate limits, Celery queue, generate/batch/estimate | | Inference (:8090 / Modal) | Kokoro/F5 TTS → MuseTalk lip-sync → FFmpeg MP4; fast-path local <500 chars | | Data | Supabase Postgres + RLS, Redis, object storage CDN | ```bash cp .env.example .env # Fill SUPABASE_* (required on Lambda; do not use .data/store.json) supabase db push ./deploy.sh docker compose up --build ``` | Command | Role | Port | | --- | --- | --- | | npm run dev | Next.js dashboard | 3000 | | npm run gateway | FastAPI | 8080 | | npm run celery:worker | Async GPU jobs | — | | npm run inference | Local GPU | 8090 | | npm run inference:modal | Serverless T4 | — | Verify: npm run verify:all ---