/venice-characters

name: venice-characters
description: Discover and use Venice public characters (persona-driven system prompts with a suggested model). Covers GET /characters (search/filter/sort/paginate), /characters/{slug}, /characters/{slug}/reviews, the Character and Review schemas, Bearer-API-key-only auth, filter semantics (adult, pro, modelId), and how to apply a character via venice_parameters.character_slug in chat completions.

Venice Characters

Characters are **published personas** on Venice — each one bundles a system prompt (plus optional context), a suggested backing model, and metadata (tags, ratings, adult / web flags). You apply a character to a 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 want to pick the right model for a character (the character's `modelId` is a suggestion; you choose the chat `model`).

Three endpoints, all tagged **Preview** (may change):

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

**Auth: Bearer API key only.** These routes do not accept x402 / `SIGN-IN-WITH-X` (a SIWX-only request gets `401`). A request with no `Authorization` header gets a `402` x402 discovery challenge rather than `401`. There is no unauthenticated access. See [`venice-auth`](../venice-auth/SKILL.md).

`GET /characters`

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

Response: `{ "object": "list", "data": [Character, ...] }` (no total count — page with `offset` until you get fewer than `limit`).

Query parameters

| Param | Type | Notes | |---|---|---| | `search` | string, ≤ 200 chars | Case-insensitive substring match on name, description, or tag. `#Tag` terms also match tags exactly (URL-encode `#` as `%23`). | | `categories` | string[], ≤ 20 (each ≤ 100 chars) | Repeat the param or comma-separate. Matches any. | | `tags` | string[], ≤ 20 (each ≤ 100 chars) | Repeat or comma-separate. Exact tag name, matches any. | | `modelId` | string[], ≤ 20 (each ≤ 200 chars) | Repeat or comma-separate. Filters on the character's stored model ID — see Gotchas. | | `isAdult` | `"true"` / `"false"` | **Exclusive**: `true` returns *only* adult characters; omitted or `false` returns only non-adult ones. | | `isPro` | `"true"` / `"false"` | `true` = only characters whose model is a Pro model in the Venice app. `false` = no filter. Overrides `modelId` when both are sent. | | `isWebEnabled` | `"true"` / `"false"` | `true` = only web-enabled characters. `false` = no filter. | | `sortBy` | enum | `featured`, `highestRating`, `highlyRated`, `highlyRatedAndRecent`, `imports`, `mostRecent`, `ratingCount`. Omitted → most imports first. | | `sortOrder` | `asc` / `desc` | Default `desc`. Only applied when `sortBy` is set. | | `limit` | integer 1–100 | Default 50. `> 100` → `400`. | | `offset` | integer ≥ 0 | Default 0. |

`sortBy` values that also **filter**:

• `featured` — only featured characters, ordered by imports.
• `highlyRated` — only characters with ≥ 2 ratings, ordered by average rating.
• `highlyRatedAndRecent` — only characters with at least one rating ≥ 3, ordered by creation date.
• `highestRating` (average rating), `ratingCount`, `imports`, `mostRecent` (creation date) only order.

Character object

| Field | Notes | |---|---| | `id` | UUID. | | `slug` | **Use this as `character_slug` in chat.** Same as the public ID in `venice.ai/c/<slug>`. | | `name`, `description` | `description` may be `null`. | | `photoUrl`, `shareUrl` | Typed nullable; `shareUrl` is `https://venice.ai/c/<slug>` (from `GET /characters/{slug}` it may also carry the author's `?ref=` referral code). | | `author` | 5-character anonymized ID derived from the author. | | `tags[]` | Tag names. | | `featured`, `adult`, `webEnabled` | Booleans. | | `modelId` | Model ID the character was built for — usually a Venice API model ID such as `venice-uncensored-1-2`, but it can be an id `/models` doesn't list; Venice's default chat model if the character has none. | | `stats` | `{ averageRating, imports, ratingCount, ratingSum, userRating }`. Missing stats come back as `0`; `userRating` is currently always `null`. | | `createdAt`, `updatedAt` | ISO-8601. |

`GET /characters/{slug}`

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

Returns `{ "object": "character", "data": Character }`. `404` if the character doesn't exist, isn't approved/API-visible (your own characters are exempt), or is adult while your account has the mature filter on. The path also resolves a character's UUID `id`.

`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"

| Param | Notes | |---|---| | `page` | Integer ≥ 1. Default 1. | | `pageSize` | Integer 1–100. Default 20. |

Response (newest first; hidden reviews excluded):

{
  "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/..."
    }
  ]
}

• `rating` is an integer 1–5; `message`, `locale`, `userAvatarUrl` may be `null`. `isOwner` is `true` for reviews written by the calling account.
• `pagination.total` counts visible reviews; `summary.totalReviews` is the character's overa