--- title: "list personas" method: GET path: "/v1/personas" tags: ["Personas"] --- # list personas `GET /v1/personas` Returns a list of all personas ## Query parameters - `page` integer - `perPage` integer - `search` string ## Response `200` Successfully retrieved personas - object - `data` PersonaSummary[] - `id` string, uuid — Unique identifier for the persona. - `name` string — Human-readable name of the persona. - `description` string — Free-form description of the persona. Empty string if none was provided. - `personaPreset` string — Name of the preset the persona was cloned from, or empty string if it was built from scratch. - `avatar` Avatar — A face preset that a persona can use as its visual representation. - `id` string, uuid — Unique identifier for the avatar. - `displayName` string — Human-readable name shown in the Lab and share links. - `variantName` string — Name of the specific variant (e.g. lighting or pose) within the avatar family. - `imageUrl` string, uri — URL of the still image used as a preview of the avatar. - `landscapeImageUrl` string, uri, nullable — Preview image cropped exactly as the engine frames landscape (1152x768) output. Use this when displaying the avatar at a landscape aspect ratio. For avatars with legacy landscape source images this is the same as `imageUrl`. - `portraitImageUrl` string, uri, nullable — Preview image cropped exactly as the engine frames portrait (768x1152) output. Use this when starting a session with portrait `videoWidth`/`videoHeight`. `null` when the avatar cannot render portrait output. - `videoUrl` string, uri, nullable — Signed URL for a muted MP4 preview of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. - `idleVideoUrl` string, uri, nullable — Signed URL for a muted idling-loop MP4 of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when unavailable or still generating. - `createdAt` string, date-time — Timestamp when the avatar was created. - `updatedAt` string, date-time — Timestamp when the avatar was last updated. - `createdByOrganizationId` string, nullable — ID of the organization that created the avatar, or `null` for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. - `availableVersions` string[] — Avatar models this avatar can be used with. Pass one of these values as `avatarModel` when creating a persona or starting a session. - `activeVersion` string, nullable — Avatar model used by default when no explicit `avatarModel` is requested. - `description` string, nullable — AI-generated description of the avatar's appearance, setting, and style. `null` if metadata generation has not completed. - `displayTags` string[] — Curated tags describing the avatar. Empty array if metadata generation has not completed. - `renderStyle` 'realistic' | 'animated_3d' | 'illustrated' | 'unknown' — Render style of the avatar. `unknown` covers custom avatars and avatars whose metadata has not yet been generated. - `voice` Voice — A voice preset a persona can use for text-to-speech. - `id` string, uuid — Unique identifier for the voice. - `displayName` string — Human-readable name shown in the Lab. - `provider` 'CARTESIA' | 'ELEVENLABS' | 'OPENAI_ADVANCED_VOICE' | 'FISH_AUDIO' — Upstream TTS provider for this voice. - `providerVoiceId` string, nullable — The upstream provider's identifier for the voice. - `providerModelId` string, nullable — The upstream provider's model identifier used to generate speech. - `sampleUrl` string, uri, nullable — URL of a short audio preview of the voice. - `previewSampleUrl` string, uri, nullable — Alias for `sampleUrl`, kept for backwards compatibility. - `gender` 'MALE' | 'FEMALE' | 'NEUTRAL' | 'null', nullable — Perceived gender of the voice, if categorised. - `country` string, nullable — ISO 3166-1 alpha-2 country code representing the voice's accent. - `description` string, nullable — Free-form description of the voice's character. - `displayTags` string[] — Tags used to categorise the voice in the Lab UI. - `isZdr` boolean — Whether this voice meets the Zero Data Retention requirements. - `createdByOrganizationId` string, nullable — ID of the organization that created the voice, or `null` for stock voices. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. - `createdAt` string, date-time — Timestamp when the voice was created. - `updatedAt` string, date-time — Timestamp when the voice was last updated. - `voiceSpeed` number, nullable — Speech rate multiplier applied to the voice. - `isDefaultPersona` boolean — Whether this is a built-in default persona available to every organization. - `languageCode` string — ISO 639-1 language override for transcription, or `inherit` to fall back to the organization default. - `createdAt` string, date-time — Timestamp when the persona was created. - `updatedAt` string, date-time — Timestamp when the persona was last updated. - `meta` Pagination — Pagination metadata returned alongside the `data` array of every list endpoint. - `total` integer — Total number of items across all pages. - `lastPage` integer — Number of the last page. - `currentPage` integer — Number of the current page. - `perPage` integer — Number of items per page. - `prev` integer, nullable — Number of the previous page, or null if on the first page. - `next` integer, nullable — Number of the next page, or null if on the last page. ## Other responses - `401` — Unauthorized - Invalid or missing API key - `403` — Forbidden - API key lacks the required permission - `500` — Server error --- [API](https://skmtc.net/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.net/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anam/anam-ai-api/versions/67afd1c5db59/schema)