Personas API

Browse, search, and filter the library of 500 AI personas. Each persona has a defined appearance, voice style, and category.

Choosing a Persona

Use the category and voice_style filters to find personas that match your product and tone. Then pass the persona's persona_id to the Create Job endpoint.

List Personas

Retrieve a paginated list of personas with optional filters.

GET/api/v1/personas

Parameters

Parameter	Type	Description
`category`	string	Filter by category. beautyecommerceeducationfinancefitnessgaminghealthsaastech
`gender`	string	Filter by gender. femalemalenon-binary
`ethnicity`	string	Filter by ethnicity (partial match).
`age_range`	string	Filter by age bracket (e.g., "26-35").
`voice_style`	string	Filter by voice tone. calmcasualconfidentenergeticfriendlyprofessionalwarm
`tag`	string	Filter by content/industry tag.
`sort_by`	string Default: name	Sort field. nameusage_countcreated_atcategory
`sort_order`	string Default: asc	Sort direction. ascdesc
`page`	integer Default: 1	Page number. Min 1
`page_size`	integer Default: 50	Results per page. 1–100

Request Example

curl -X GET "https://api.u-gen.ai/api/v1/personas?category=beauty&gender=female&page=1&page_size=10" \
  -H "X-API-Key: YOUR_API_KEY"

Get Persona

Retrieve full details for a single persona by ID or slug.

GET/api/v1/personas/{persona_id}

Path

Parameter	Type	Description
`persona_id`REQ	string (UUID or slug)	Persona UUID or URL slug.

Request Example

curl -X GET https://api.u-gen.ai/api/v1/personas/09d3a33a-3eb0-480a-80df-0c64dbf7c98f \
  -H "X-API-Key: YOUR_API_KEY"

Search Personas

Free-text search across persona names and descriptions.

GET/api/v1/personas/search

Parameters

Parameter Type Description

Parameter	Type	Description
`q`REQ	string	Search query. Min 2 characters
`limit`	integer Default: 20	Max results. 1–50

qREQ

string

Search query.

Min 2 characters

limit

integer

Default: 20

Max results.

1–50

Request Example

curl -X GET "https://api.u-gen.ai/api/v1/personas/search?q=fitness&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

Get Filter Options

Returns unique values for all filterable fields. Use this to populate dropdown menus.

GET/api/v1/personas/filter-options

Request Example

curl -X GET https://api.u-gen.ai/api/v1/personas/filter-options \
  -H "X-API-Key: YOUR_API_KEY"

Additional Endpoints

The Personas API also includes GET /personas/random (random persona, optionally filtered by category), POST /personas/by-ids (batch lookup, max 50 IDs), and GET /personas/categories (list of unique categories).