Skip to the content
ENTIQAPI docs
API keys
Menu: Personas and duos

Personas and duos

A persona (pa_…) is an avatar people talk to: a face, a voice, instructions (systemPrompt), a first line (greeting), what it knows, and how it speaks. Personas are what live sessions start with, and what speaks on your portals and your website.

Faces and voices#

  • Faces (av_…): GET /v1/avatars lists the library's people and your own. Your own come from a head-and-shoulders picture (POST /v1/avatars).
  • Voices (vo_…): GET /v1/voices lists studio voices and your own clones (POST /v1/voices, from 10 to 60 seconds of clean speech, where the plan includes cloning). Each lists the languages it speaks: a studio voice every language in the catalogue, a cloned voice the ten a duo speaks.
  • The voice decides how the persona speaks, as it does in the console: choose the voice (voiceId), and the rest follows. A persona's settings.engine says what that is, and can't be written (a key on the 2026-07-08 contract may still send it; it changes nothing).

Consent#

A face or a voice of a real person needs that person's consent. The requests that make them take a consent object: who it is (myself or someone_else, with their name) and that they agreed (attested: true). A face made by AI is subject: "generated"; a voice can't be. Zentiq keeps the consent as a record, with the key, the time and the words agreed to. Without it the request is 400 consent_required (or consent_invalid, or consent_outdated when the wording changed). If consent is later withdrawn, sessions with that face or voice stop starting (409 consent_withdrawn).

Languages#

GET /v1/languages is the catalogue: every language an avatar speaks, with its code, its name, its own name, and whether a duo speaks it. Languages are given by code (es, pt-BR) or English name.

  • settings.language is the persona's language.
  • settings.languageMode: follow answers each person in the language they use; fixed keeps the persona's language whatever they speak.
  • A session can override both when it starts (language, languageMode), and change language while it runs.

Knowledge#

A knowledge pack (kb_…) is a set of documents (doc_…) a persona answers from: a web page, a file (PDF, Word, text, Markdown, CSV) or text you send. Reading a document takes a moment: it is processing, then ready (the knowledge.document.processed event says so) or failed (with an errorCode). A document with no text in it (an empty file, a scanned page saved as a PDF) fails with empty, never ready with nothing to answer from. Attach packs to a persona with knowledge.baseIds; one pack can serve many personas.

Duos#

A duo (duo_…) is two people in one conversation: a couple buying a home, a buyer and their finance director. Duos are made in the console's duo studio, or added from Zentiq's duo library (POST /v1/duos with a library key). Every duo is checked before people meet it: POST /v1/duos/{id}/publish sends it for a render check, and it becomes live when that passes (or needs_changes, with what to fix).

  • A duo has a persona of its own, named after both people: "Mark & Susan". Start sessions and build portals with that persona id. A persona you name with an "&" is still one person: only a duo is two.
  • A duo's persona is changed in the duo studio, never with PATCH /v1/personas/{id} (409 conflict, with details.reason duo_studio_only).
  • GET /v1/personas?kind=duo lists the duos' personas; each names its duo in duoId, and every persona its people in cast.
  • Before it is live, a session with it is 409 duo_not_live, and a portal with it is refused.
  • A duo speaks fewer languages than one avatar: those GET /v1/languages marks with duo: true.
  • A duo counts as a custom avatar against the plan.

The browser SDK names the person speaking in a duo's captions: see Browser.