Avatars

Faces: the library and your own.

GET/v1/avatars

List avatars (the library and your own)

listAvatarsavatars:readread: 600/min per key

The library's faces first, then your organisation's own, oldest first.

Query parameters

limitinteger
Page size, 1-200 (default 50).
cursorstring
The nextCursor of the previous page.
kind"builtin" | "custom"
builtin: the library only; custom: your own only.
gender"female" | "male"
ageBand"20s" | "30s" | "40s" | "50s" | "60s"
heritagestring (one of 10)

Returns

200 A page of avatars. A page: data is a list of Avatar, and nextCursor fetches the next page.

Fields of data

idstringrequired
Avatar id (av_…).
pattern `^av_.*`
namestringrequired
kind"builtin" | "custom"required
builtin: Zentiq's library; custom: your organisation's own.
genderstring | nullrequired
A library face's gender (female, male); null for your own pictures.
ageBandstring | nullrequired
A library face's age band (20s, 30s, 40s, 50s, 60s); null for your own.
heritagestring | nullrequired
A library face's heritage (white, black, indian, chinese, korean, japanese, thai, hispanic, middleeastern, mixed); null for your own.
previewUrlstring | nullrequired
The picture. A library face is public (usable in an <img>); your own needs your API key (or a console sign-in).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
aiGeneratedtruerequired
Always true: this avatar's video and voice in every session are AI-generated, and so is its picture unless it is a photo you uploaded (EU AI Act Article 50(2)).

Errors

invalid_request unauthorized forbidden upgrade_required rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/avatars?limit=20" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const page = await zentiq.listAvatars({
  limit: 20,
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
page = zentiq.list_avatars(limit=20)

Example answer

Response

{
  "data": [
    {
      "id": "av_cmfq2b7x10000abcd1234",
      "name": "Zoe",
      "kind": "builtin",
      "gender": "…",
      "ageBand": "…",
      "heritage": "…"
    }
  ],
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d",
  "nextCursor": null
}

POST/v1/avatars

Bring your own avatar picture

createAvataravatars:writewrite: 120/min per keyIdempotency-Key

A close head-and-shoulders portrait, inline as a data:image URI or fetched from a public https address (6 MB at most); a plain green background gives the cleanest live cut-out. It counts against the plan's custom avatars (403 upgrade_required when there is no room). consent is required (400 consent_required before the picture is fetched): it is kept as a consent record the organisation's owners can export and withdraw, and withdrawing it stops the avatar starting new sessions.

Body

namestring
Default "Custom avatar".
imageBase64string
The picture as a data:image/… URI (PNG, JPEG or WebP).
imageUrlstring (uri)
Or a public https address to fetch it from (6 MB at most).
consentConsentrequired
Consent to clone a real person's voice or to make an avatar from their picture. Recorded with who confirmed it (the API key), when, a hashed IP address, the exact wording and its version. The organisation's owners can export records and withdraw them; a withdrawn voice or face stops starting new sessions.

Returns

201 The new avatar. data is Avatar.

Fields of data

idstringrequired
Avatar id (av_…).
pattern `^av_.*`
namestringrequired
kind"builtin" | "custom"required
builtin: Zentiq's library; custom: your organisation's own.
genderstring | nullrequired
A library face's gender (female, male); null for your own pictures.
ageBandstring | nullrequired
A library face's age band (20s, 30s, 40s, 50s, 60s); null for your own.
heritagestring | nullrequired
A library face's heritage (white, black, indian, chinese, korean, japanese, thai, hispanic, middleeastern, mixed); null for your own.
previewUrlstring | nullrequired
The picture. A library face is public (usable in an <img>); your own needs your API key (or a console sign-in).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
aiGeneratedtruerequired
Always true: this avatar's video and voice in every session are AI-generated, and so is its picture unless it is a photo you uploaded (EU AI Act Article 50(2)).

Errors

invalid_request consent_required consent_invalid consent_outdated unauthorized forbidden upgrade_required idempotency_conflict idempotency_in_progress too_large rate_limited server_error

Request

curl -X POST "https://app.zentiqai.com/v1/avatars" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "consent": {
    "attested": true,
    "subject": "myself"
  }
}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.createAvatar({
  consent: {
    attested: true,
    subject: "myself",
  },
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.create_avatar({
    "consent": {
        "attested": True,
        "subject": "myself",
    },
})

Example answer

Response

{
  "data": {
    "id": "av_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "kind": "builtin",
    "gender": "…",
    "ageBand": "…",
    "heritage": "…"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/avatars/{id}

Get an avatar

getAvataravatars:readread: 600/min per key

Path parameters

idstringrequired
Avatar id (av_…); the id without its prefix is accepted too.

Returns

200 The avatar. data is Avatar.

Fields of data

idstringrequired
Avatar id (av_…).
pattern `^av_.*`
namestringrequired
kind"builtin" | "custom"required
builtin: Zentiq's library; custom: your organisation's own.
genderstring | nullrequired
A library face's gender (female, male); null for your own pictures.
ageBandstring | nullrequired
A library face's age band (20s, 30s, 40s, 50s, 60s); null for your own.
heritagestring | nullrequired
A library face's heritage (white, black, indian, chinese, korean, japanese, thai, hispanic, middleeastern, mixed); null for your own.
previewUrlstring | nullrequired
The picture. A library face is public (usable in an <img>); your own needs your API key (or a console sign-in).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
aiGeneratedtruerequired
Always true: this avatar's video and voice in every session are AI-generated, and so is its picture unless it is a photo you uploaded (EU AI Act Article 50(2)).

Errors

invalid_request unauthorized forbidden upgrade_required not_found gone rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/avatars/av_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getAvatar("av_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_avatar("av_123")

Example answer

Response

{
  "data": {
    "id": "av_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "kind": "builtin",
    "gender": "…",
    "ageBand": "…",
    "heritage": "…"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

DELETE/v1/avatars/{id}

Delete one of your avatars

deleteAvataravatars:writewrite: 120/min per key

Refused (409) while a persona still wears it: give that persona another face, or delete it, first. Library faces can't be deleted.

Path parameters

idstringrequired
Avatar id (av_…); the id without its prefix is accepted too.

Returns

200 Deleted. data is object.

Fields of data

deletedtruerequired
idstringrequired
Avatar id (av_…).
pattern `^av_.*`

Errors

invalid_request unauthorized forbidden upgrade_required not_found conflict rate_limited server_error

Request

curl -X DELETE "https://app.zentiqai.com/v1/avatars/av_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.deleteAvatar("av_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.delete_avatar("av_123")

Example answer

Response

{
  "data": {
    "deleted": true,
    "id": "av_cmfq2b7x10000abcd1234"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/avatars/{id}/preview

An avatar's picture

avatarPreviewNo key

A library face is public: link it from an <img> with no header. Your organisation's own pictures (uploaded or generated) are shown only to your organisation: send an API key holding avatars:read in the Authorization header; anyone else gets 404, never a hint that the id exists.

Path parameters

idstringrequired
Avatar id (av_…); the id without its prefix is accepted too.

Returns

200 The picture (PNG, JPEG or WebP). (image/*, not the JSON envelope)

Errors

invalid_request not_found server_error

Request

curl "https://app.zentiqai.com/v1/avatars/av_123/preview"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const bytes = await zentiq.avatarPreview("av_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.avatar_preview("av_123")