venice--venice-characters

Venice Characters

Characters are published personas on Venice — each one bundles a system prompt, a backing model, optional web access, and metadata (tags, ratings, adult flag). You apply a character to any chat by passing its slug via venice_parameters.character_slug.

Use when

• You want to build a character-selection UI or discovery surface.
• You want to ship an app with a preset persona (e.g. a coding coach, a philosopher, a game NPC).
• You need to adapt a character's underlying model (modelId) to match your capability requirements.

Three endpoints, all under Preview (API may change):

Endpoint	Purpose
GET /characters	Browse/search/filter the catalog.
GET /characters/{slug}	Fetch one character.
GET /characters/{slug}/reviews	Paginated public reviews.

All three endpoints require authentication (Bearer API key or x402 SIWE) — see venice-auth. There is no unauthenticated public endpoint.

GET /characters

curl "https://api.venice.ai/api/v1/characters?search=philosopher&sortBy=highestRating&limit=20" \
  -H "Authorization: Bearer $VENICE_API_KEY"

Query parameters

Param	Type	Notes
search	string, ≤ 200	Name, description, or tag match. Hashtag (#Philosophy) supported.
categories	string[], ≤ 20	Repeat or comma-separate. Character categories (roleplay, philosophy, …).
tags	string[], ≤ 20	Repeat or comma-separate.
modelId	string[], ≤ 20	Filter by backing model (zai-org-glm-5-1, kimi-k2-6, minimax-m25, …).
isAdult	"true" / "false"	Adult-content flag.
isPro	"true" / "false"	Require a Pro model.
isWebEnabled	"true" / "false"	Allow web access.
sortBy	enum	featured, highestRating, highlyRated, highlyRatedAndRecent, imports, mostRecent, ratingCount.
sortOrder	asc / desc	Default desc.
limit	1–100	Default 50.
offset	integer	Pagination offset.

Character object

Field	Notes
id	UUID.
slug	Use this as character_slug in chat. URL-safe.
name, description, photoUrl, shareUrl	Presentation.
author	Anonymized short ID.
tags[], featured, adult, webEnabled	Metadata.
modelId	Backing Venice model ID (e.g. venice-uncensored).
stats	{averageRating, imports, ratingCount, ratingSum, userRating}.
createdAt, updatedAt	ISO-8601.

GET /characters/{slug}

curl "https://api.venice.ai/api/v1/characters/alan-watts" \
  -H "Authorization: Bearer $VENICE_API_KEY"

Returns the same object shape above, wrapped as { object: "character", data: { ... } }. 404 if the slug is unknown or unpublished.

GET /characters/{slug}/reviews

curl "https://api.venice.ai/api/v1/characters/alan-watts/reviews?page=1&pageSize=20" \
  -H "Authorization: Bearer $VENICE_API_KEY"

Response:

{
  "object": "list",
  "pagination": {"page": 1, "pageSize": 20, "total": 87, "totalPages": 5},
  "summary": {"averageRating": 4.7, "totalReviews": 87},
  "data": [
    {
      "id": "...", "characterId": "...", "createdAt": "...",
      "rating": 5, "message": "Thoughtful and grounded.",
      "locale": "en", "username": "product_user_42", "isOwner": false,
      "userAvatarUrl": "https://cdn.venice.ai/..."
    }
  ]
}

Also sets x-pagination-* response headers (limit, page, total, total-pages).

Using a character in chat

Minimal

{
  "model": "zai-org-glm-5-1",
  "venice_parameters": { "character_slug": "alan-watts" },
  "messages": [
    { "role": "user", "content": "What's the nature of mind?" }
  ]
}

The character's system prompt is injected by Venice. include_venice_system_prompt defaults to true and adds Venice's curated prelude — set it to false for a pure character voice.

Ignoring the character's backing model

You can override the model — Venice will still apply the character's system prompt:

{
  "model": "kimi-k2-6",
  "venice_parameters": {
    "character_slug": "alan-watts",
    "include_venice_system_prompt": false
  },
  "messages": [...]
}

Useful when the character's modelId lacks a capability (e.g. function calling, vision) that your app needs.

Via feature suffix on the model string

{ "model": "zai-org-glm-5-1:character_slug=alan-watts", "messages": [...] }

Useful when the client library (OpenAI SDK, LangChain, etc.) can't add venice_parameters. See venice-chat for the full suffix grammar.

Patterns

Character picker UI

const res = await fetch(`${base}/characters?sortBy=featured&limit=50`, {
  headers: { Authorization: `Bearer ${process.env.VENICE_API_KEY}` },
})
const { data } = await res.json()
// show data[].photoUrl, data[].name, data[].stats.averageRating
// pick a slug, then pass into chat:
await chat({
  model: pickedModelId,
  venice_parameters: { character_slug: pickedSlug },
  messages: [...]
})

Filter for family-friendly + web

/characters?isAdult=false&isWebEnabled=true&sortBy=highlyRatedAndRecent

Search by hashtag

/characters?search=%23Philosophy

Errors

Code	Meaning
400	Bad query params (e.g. limit > 100).
401	Missing or invalid auth. All three endpoints require a Bearer key or SIWE header.
404	Unknown slug.
500	Transient. Retry.

Gotchas

• This is Preview API — response shape may change.
• Slugs are the public ID on the character's page (venice.ai/c/<slug>). They are not the internal id UUID.
• photoUrl / shareUrl / userAvatarUrl can be null — don't assume they exist.
• Character modelId may be gated (Pro, beta). If you always reuse the character's modelId, handle 401 "only available to Pro users" gracefully.
• Adult-flagged characters are omitted unless isAdult=true is explicitly passed.