REST API

Plan, limits and the live token balance (1 token = $0.01). tokens_included is the plan’s number each period; tokens_granted is what this period actually holds, the plan plus any top-ups and grants, so tokens_left = tokens_granted − tokens_used. tokens_available adds the extra tokens still allowed under the spending cap and is the figure every gate checks.

{ "id": "org_…", "name": "Harbor Dental", "plan": "pro", "plan_label": "Pro",
  "token_usd": 0.01, "tokens_included": 22500, "tokens_granted": 23500, "tokens_left": 16369, "tokens_used": 7131, "tokens_available": 56169, "minutes_left": 545.6,
  "live_at_once": 3, "avatars_max": 3, "embed_domains_max": 5, "premium_multiplier": 2,
  "live_tokens_per_minute": { "lite": 30, "premium": 60 },
  "studio_tokens": { "openai": { "standard": 4, "high": 13, "max": 50 }, "google": { "standard": 40, "high": 40, "max": 72 }, "google-nb21": { "standard": 10, "high": 15, "max": 34 } },
  "extra_token_usd": 0.01, "spending_cap_usd": 398, "extra_tokens_allowed": 39800, "extra_tokens_used": 0, "extra_cost_usd": 0,
  "period_start": "2026-10-01T00:00:00.000Z", "billing_interval": "month", "paid_until": null, "transcript_days": 30 }

Owners and admins set the spending cap for extra tokens, { "spending_cap_usd": 200 } (0 stops at the allowance), and how long conversations are kept, { "transcript_days": 90 } (1 to 365, default 30). Either field alone.

Build an avatar from a photo. multipart/form-data:

By building an avatar you confirm you have the right to use the photo and the person’s likeness, as the terms set out; nothing is signed per avatar. If you keep your own releases you may send person_name, person_email, is_adult=yes, uses and signed_name and the release is kept on file.

Every photo is checked first (a few seconds, free). A photo with no face or more than one person is refused with 422 photo.no_face or photo.faces, and nothing is stored. The photo is built as you framed it and never cropped by itself, so a full figure or a wide composition stays as it is. When the face would come out small that way, photo_check.crop_suggested is true (the dashboard shows “Your avatar might look better with a crop”): send framing=portrait, or rebuild with it later, to crop to the face, free.

Returns 202 with the avatar in status building. Poll GET /avatars/:id until ready (about a minute on a warm engine) or failed with an error.

When the expression would animate badly (teeth showing, a big smile, an open mouth, eyes looking away or shut) the status is needs_approval instead, photo_check.findings says why, and approval carries a link and a price: { "url": "https://app.avaclone.ai/avatars/ava_…?approve=1", "tokens": 40 }. Send a person to that link: they sign in to AvaClone and approve the tokens, the photo is regenerated with a calm, closed-mouth smile and nothing else changed, checked again, and the build starts (status fixing, then building). The fix is charged only when it passes; if it does not, the avatar goes back to needs_approval with photo_check.fix_error and nothing is charged. An API key cannot approve.

{ "id": "ava_…", "status": "needs_approval",
  "photo_check": { "status": "fix", "findings": ["Teeth are showing. The avatar draws teeth poorly; they can blur into the gums."],
                   "expression": "big_smile", "teeth_visible": true, "mouth_open": true, "gaze": "camera", "eyes": "open",
                   "crop_suggested": false, "fixed": false, "fix_error": null },
  "approval": { "url": "https://app.avaclone.ai/avatars/ava_…?approve=1", "tokens": 40 }, … }

Your avatars with status, engine (lite or premium) and the idle loop URL once ready.

One avatar. framing is head_and_shoulders (the whole person, as framed) or portrait (cropped to the face, centred and sized for the model); photo_check.crop_suggested says when the crop would likely look better.

Any of name, voice_id and face_restore. { "face_restore": true } turns on Face Restore (beta): sharper eyes, lips and teeth on every frame of this avatar’s live sessions and videos, for restore_tokens_per_minute more tokens a minute (5 today, on either tier; the number is on GET /organization). It applies to sessions and videos made after the change, and is charged only when it ran: when the GPU is busy a session can run without it. The idle loop (idle_loop_url, what a page shows before the stream is live) is always made with Face Restore, free, whatever this says; idle_restored tells you it was.

Rebuild from the stored photo, free, with everything the engine now does. The avatar keeps its framing unless you send { "framing": "portrait" } (crop to the face) or { "framing": "head_and_shoulders" } (back to the whole person). 409 while a build runs or the avatar waits for its expression fix.

Remove it. Agents using it stop starting sessions until they are given another.

{ "name": "Front desk", "avatar_id": "ava_…" }. Creates a draft with sensible defaults (a stock voice, mixed grounding, vision on, 40 turns an hour, 400 a day, a two-minute quiet cut-off).

All agents with their draft and publish state.

One agent: the draft configuration flattened, status (draft or published), published_version, draft_changed.

Change the draft. Any subset:

{ "name": "Front desk", "display_name": "Lindsey",
  "avatar_id": "ava_…", "voice_id": "stock_warm_f",
  "charter": {
    "purpose": "Answer questions about the practice and book appointments by phone.",
    "audience": "Patients and people choosing a dentist.",
    "tone": "Warm, brief, plain.",
    "greeting": "Hi, I'm the Harbor Dental assistant. What can I help with?",
    "return_greeting": "Welcome back! Where were we?",
    "topics": ["hours", "insurance", "services"],
    "boundaries": ["No medical advice; suggest a visit."],
    "unknown_handling": "Say you are not sure and offer the phone number.",
    "facts": ["Open Monday to Friday 8 to 5."],
    "sample_qa": [{ "q": "Do you take Delta Dental?", "a": "Yes, we are in network." }]
  },
  "grounding": "knowledge_only",
  "vision": true, "expressive_voice": true, "voice_cues": ["sympathetic", "thoughtful", "short pause"], "language": "en",
  "limits": { "turns_per_hour": 40, "turns_per_day": 400, "quiet_cutoff_s": 120 } }

grounding: knowledge_only answers only from your files and facts; mix adds general knowledge; model_only ignores files.

expressive_voice (Pro plan and above): the voice performs a cue such as a chuckle or a sympathetic tone when the moment in the conversation calls for one, always in keeping with charter.tone; a serious or gruff tone keeps cues out of nearly every answer and never laughs. It is on for every agent on Pro and above (and switches on for all of an organization’s agents when it moves up to Pro); turning it on below Pro returns 403 plan.required. voice_cues lists the cues the agent may use (null, the default, allows any that suits its tone); the voice drops any other, even if the model writes it. The cues are listed under Your own model, our face and voice. Captions and transcripts never show them.

language: the language visitors usually speak, as an ISO 639-1 code (en by default; also es, fr, pt, de, it, zh, vi, tl, ko, ja, hi, ar, ru, uk, pl, nl, tr, he). It guides rather than limits: speech recognition expects it and the agent answers in it, but a visitor who plainly speaks another language is understood and answered in theirs. One short line heard in another alphabet, such as a quick “yeah” or a TV mistaken for Korean, is ignored; a second line in a row in that alphabet is taken as the visitor’s language.

charter.return_greeting: what the agent says instead of the greeting when a visitor picks an earlier conversation back up, after the quiet cut-off ended it, after they closed the panel, or after a reload in the same tab. The agent remembers the earlier conversation (its last eight exchanges) either way. Blank: “Welcome back! What else can I help you with?” for an English agent, no scripted line for another language.

display_name: the name visitors see, above the face in the widget and as the hosted page’s title, and the name the agent gives when it introduces itself or is asked. name stays your own label for the agent (“Front desk”). null or blank, the default, uses name. Like everything else, visitors get it with the next publish. Use the same name in charter.greeting and the persona.

Remove the agent and its embed.

Freeze the draft as the next version. Visitors get it at once; live sessions finish on the version they started with.

Every published version with its configuration.

{ "version": 3 } rolls back: that version becomes the published one and the draft.

multipart/form-data with file (PDF, text or Markdown, up to 10 MB). The file is chunked and embedded in the background; GET shows its status.

Files with status (indexing, ready, failed) and chunk counts.

Remove a file and its chunks.

The publishable id, allowed domains, appearance and ready-to-paste snippets:

{ "agent_id": "agt_…", "publishable_id": "pub_…",
  "allowed_domains": ["harbordental.com", "www.harbordental.com"],
  "appearance": { "position": "bottom_right", "launcher_size": "medium", "launcher_label": "Talk to us", "theme": "auto", "accent": "#0052FF", "captions": true, "background": "avatar" },
  "snippets": { "script": "<script src=…>", "inline": "…", "iframe": "<iframe …>", "hosted_url": "https://app.avaclone.ai/a/pub_…" } }

{ "allowed_domains": ["…"], "appearance": { … } }. Domain count is per plan.

A new publishable id; the old one stops working at once.

Start a conversation for your own UI (the SDK). Checks tokens and the live cap first.

{ "id": "ses_…", "ws_url": "wss://rt.avaclone.ai/v1/sessions/ses_…", "token": "…",
  "expires_at": "2026-10-07T21:10:00.000Z", "idle_loop_url": "https://app.avaclone.ai/m/ses_…/idle", "packed": true,
  "engine": "lite", "resumed_from": null }

Give ws_url, token and idle_loop_url to the browser. The token is single-use and expires in ten minutes.

Your own model, our face and voice

To keep your own LLM, knowledge and conversation logic and use AvaClone only for the avatar and the voice, start a stream session with an avatar_id and, if you like, a voice_id. Then, each time your model has something to say, send the text and the avatar says it: the words are read aloud in that voice and the face is lip-synced live. Nothing else is needed; there is no agent, no listening and no knowledge on our side. Send a line per sentence or paragraph as your model produces it; lines are spoken in order, and interrupt() cuts the current one and drops the rest. If you already generate speech yourself, send 24 kHz PCM instead and the face follows it.

curl https://app.avaclone.ai/api/v1/sessions \
  -H "Authorization: Bearer ak_live_…" -H "Content-Type: application/json" \
  -d '{ "kind": "stream", "avatar_id": "ava_…", "voice_id": "vce_…" }'

// in the browser, with the ws_url and token from your server
import { AvaClone } from "https://cdn.avaclone.ai/v1/sdk.js";
const avatar = AvaClone.mount(document.querySelector("#face"), { wsUrl, token, idleLoopUrl });
avatar.sendText("Thanks for calling. We're open until 6 today, and parking is free after 5.");   // from your own model

Before anything is spoken, symbols are read the way a person would say them: $20.10 is “twenty dollars and ten cents”, 72°F is “seventy-two degrees Fahrenheit”, 5–10 is “five to ten”, markdown and emoji are dropped. The transcript event carries your text as you sent it, without audio tags.

Audio tags. A cue in square brackets is performed by the voice rather than read: avatar.sendText("[chuckles] Fair enough. We open at nine."). The cues are [laughs] [chuckles] [sighs] [exhales] [clears throat] [short pause] [long pause] [warmly] [softly] [happy] [excited] [curious] [thoughtful] [surprised] [sympathetic] [reassuring]; any other bracketed text is dropped, never read aloud. Put the cue just before the words it colours. A cue counts toward the line’s length but never shows in captions or transcripts. Cues are a Pro feature: below the Pro plan they are dropped, never read aloud. Hosted agents use the same cues on their own when expressive voice is on.

Status (created, live, ended), seconds live, tokens charged, turns, how it ended.

What the widget calls; no key, checked against the embed’s domains by the request’s Origin. { "publishable_id": "pub_…", "visitor_ref": "optional id" }. The widget also sends "resume": { "session_id", "token" }, the tab’s previous session, so the agent picks the conversation up, and timezone, the browser’s, so the agent knows the visitor’s date and time. Same response as above plus the greeting, the appearance and whether the branding line shows.

{ "prompt": "…", "quality": "standard" | "high" | "max", "count": 1, "model": "google" | "google-nb21" | "openai" }. Draws 4 to 72 tokens per image by model and quality (see studio_tokens on the organization). Returns a job; poll GET /images/jobs/:id for image_ids.

{ "prompt": "make the background a bright office", "quality": "high" }. Edit with words; lineage is kept.

{ "style": "cartoon", "quality": "high" }. Style ids from GET /styles.

{ "background": "remove" } for a transparent PNG, or { "background": "replace", "background_value": "a bright office" }. Priced like an edit, by model and quality.

Your images; library=1 only the ones saved to the library. Each image carries prompt, the words that made it: the generate prompt, or the instruction for an edit (null for uploads, styles and backgrounds). Follow parent_id to the generated image to find the original prompt of an edited one.

{ "saved": true, "name": "…" }.

The file as a download.

Remove it.

The style catalog (id, name, description, version), the tokens per model and quality, and the models available.

Newest first. ?agent_id= narrows to one agent; ?limit= up to 100; pass the response’s next as ?before= for the next page.

curl "https://app.avaclone.ai/api/v1/conversations?agent_id=agt_…&limit=20" \
  -H "Authorization: Bearer ak_live_…"

{ "items": [ { "id": "ses_…", "agent_id": "agt_…", "agent_name": "Front desk", "kind": "agent",
    "started_at": "2026-10-12T18:04:11.000Z", "ended_at": "2026-10-12T18:06:40.000Z", "live_seconds": 149, "turns": 4, "lines": 9,
    "first_question": "What are your opening hours?", "last_line": "See you Saturday, then.", "end_reason": "quiet", "origin": "harbordental.com", "visitor_ref": null } ],
  "next": "2026-10-12T18:04:11.000Z", "transcript_days": 30 }

The conversation with messages: role (user or assistant), text, via (how the visitor said it: voice or text), at.

import os, requests

r = requests.get("https://app.avaclone.ai/api/v1/conversations/ses_…",
                 headers={"Authorization": f"Bearer {os.environ['AVACLONE_API_KEY']}"})
for line in r.json()["messages"]:
    print(line["role"], ":", line["text"])

Your library. Each voice carries kind (stock or cloned), sample_url (the voice saying one line, MP3; fetch it with the same key) and used_by (the avatars and agents that speak with it). ?kind=cloned returns only the voices you trained. voices_max and voices_used are your plan’s allowance.

curl "https://app.avaclone.ai/api/v1/voices?kind=cloned" \
  -H "Authorization: Bearer ak_live_…"

{ "items": [ { "id": "vce_7f3a…", "name": "Maya", "description": "Your upload", "gender": null, "kind": "cloned",
    "sample_url": "https://app.avaclone.ai/api/v1/voices/vce_7f3a…/sample", "created_at": "2026-10-12T18:04:11.000Z",
    "used_by": { "avatars": [ { "id": "ava_…", "name": "Maya" } ], "agents": [] } } ],
  "voices_max": 3, "voices_used": 1 }

Train a voice from audio. multipart/form-data:

Returns 201 with the voice, ready to use as voice_id at once. Errors: 400 audio.short under thirty seconds, 413 audio.size, 415 audio.type, 402 plan.voices on a plan without training, 409 voices.limit when the plan’s trained voices are all used (delete one first), 502 voice.provider if the provider refuses.

curl https://app.avaclone.ai/api/v1/voices \
  -H "Authorization: Bearer ak_live_…" \
  -F "name=Maya" \
  -F "files=@maya-sample.mp3"

// Node 20+ (fetch, FormData and Blob are built in)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("name", "Maya");
form.append("files", new Blob([await readFile("maya-sample.mp3")], { type: "audio/mpeg" }), "maya-sample.mp3");

const res = await fetch("https://app.avaclone.ai/api/v1/voices", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AVACLONE_API_KEY}` },
  body: form,
});
const voice = await res.json();           // { id: "vce_…", name: "Maya", kind: "cloned", sample_url: "…" }

import os, requests

with open("maya-sample.mp3", "rb") as f:
    res = requests.post(
        "https://app.avaclone.ai/api/v1/voices",
        headers={"Authorization": f"Bearer {os.environ['AVACLONE_API_KEY']}"},
        data={"name": "Maya"},
        files=[("files", ("maya-sample.mp3", f, "audio/mpeg"))],
    )
voice = res.json()                        # voice["id"] is the voice_id to use on an avatar or agent

One voice, with used_by.

{ "name": "…" } on a voice you trained; stock voices keep their names.

Remove a trained voice. It is deleted at the provider; avatars and agent drafts that used it fall back to Harper.

The voice saying one line, as MP3.

curl https://app.avaclone.ai/api/v1/voices/vce_7f3a…/sample \
  -H "Authorization: Bearer ak_live_…" -o maya.mp3

Returns 202 with the video in status queued. Poll GET /videos/:id until ready (about as long as the video, plus a minute if the engine was cold) or failed with an error. GET /avatars/:id/framing says beforehand which frames the photo covers, what a painted background costs and which are already paid for.

curl https://app.avaclone.ai/api/v1/videos \
  -H "Authorization: Bearer ak_live_…" -H "Content-Type: application/json" \
  -d '{ "avatar_id": "ava_…", "ratio": "16:9", "script": "Hi, I'"'"'m Harper from Harbor Dental. Here is what to expect at your first visit." }'

const res = await fetch("https://app.avaclone.ai/api/v1/videos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AVACLONE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ avatar_id: "ava_…", ratio: "9:16", script: "Hi, I'm Harper…", background: { mode: "extend" } }),
});
let video = await res.json();            // { id: "vid_…", status: "queued", tokens_estimated: 24, … }
while (video.status !== "ready" && video.status !== "failed") {
  await new Promise((r) => setTimeout(r, 5000));
  video = await (await fetch(`https://app.avaclone.ai/api/v1/videos/${video.id}`, { headers: { Authorization: `Bearer ${process.env.AVACLONE_API_KEY}` } })).json();
}
console.log(video.url, video.download_url);   // valid for an hour

import os, time, requests

h = {"Authorization": f"Bearer {os.environ['AVACLONE_API_KEY']}"}
video = requests.post("https://app.avaclone.ai/api/v1/videos", headers=h,
                      json={"avatar_id": "ava_…", "ratio": "1:1", "script": "Hi, I'm Harper…"}).json()
while video["status"] not in ("ready", "failed"):
    time.sleep(5)
    video = requests.get(f"https://app.avaclone.ai/api/v1/videos/{video['id']}", headers=h).json()
open("harper.mp4", "wb").write(requests.get(video["download_url"]).content)

The library, newest first, without playback URLs. ?avatar_id= narrows it to one avatar.

One video. Once ready, url plays and seeks straight from storage and download_url saves it as a file; both are valid for an hour, so fetch the video again for fresh ones.

{ "name": "…" }.

Remove it from the library; the file is deleted at once. A video still rendering waits until it finishes.

A 302 to a short-lived storage URL that saves under the video’s name.

{ "name": "production server" }; the secret is in the response once.

Names, prefixes, last use.

Revoke.

Members, open invites and seats (signed-in people only).

{ "email": "…", "role": "member" | "admin" }; returns the one-time invite link.