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.

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/. |
| name, description | description may be null. |
| photoUrl, shareUrl | Typed nullable; shareUrl is https://venice.ai/c/ (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 overall rating count, so the two can differ.
• Also sets x-pagination-limit, x-pagination-page, x-pagination-total, x-pagination-total-pages headers.

Using a character in chat

Minimal

{
  "model": "venice-uncensored-1-2",
  "venice_parameters": { "character_slug": "alan-watts" },
  "messages": [
    { "role": "user", "content": "What's the nature of mind?" }
  ]
}

What Venice does with the slug:

• Prepends the character's system prompt (and any character context messages) to your conversation.
• include_venice_system_prompt defaults to true; set it to false for a pure character voice. Characters configured with a custom system prompt turn the Venice prompt off automatically.
• Unknown or non-API-visible slug → 404 "No character could be found from the provided character_slug".
• E2EE requests skip character injection — when an E2EE model is called with the E2EE headers, the slug is silently ignored. The same model in TEE-only mode (no E2EE headers, or enable_e2ee: false) applies the character.

character_slug is also accepted in venice_parameters on /responses — see venice-responses.

Choosing the model

The request model is always what runs — Venice does not switch to the character's modelId. Use the character's modelId if you want the experience its author intended, or any other chat model if you need a capability it lacks (function calling, vision, reasoning):

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

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 character, then pass its slug (and its modelId if it appears in GET /models) into chat:
await chat({
  model: picked.modelId,
  venice_parameters: { character_slug: picked.slug },
  messages: [...]
})

Web-enabled, family-friendly, recent and well-rated

/characters?isWebEnabled=true&sortBy=highlyRatedAndRecent

(Non-adult is already the default; isAdult=false is redundant.)

Search by hashtag

/characters?search=%23Philosophy

Errors

| Code | Meaning |
|---|---|
| 400 | Bad query params (e.g. limit > 100, pageSize > 100, unknown sortBy, search > 200 chars, > 20 array items). |
| 401 | Unknown, expired or revoked API key, or SIWX-only auth (not supported here). |
| 402 | No Authorization header — x402 discovery challenge. Send a Bearer key. |
| 404 | Unknown / unapproved / hidden slug (also adult characters when the account's mature filter is on). |
| 429 | Too many failed requests (the error-rate limiter). |
| 500 | Transient. Retry. |

Gotchas

• This is a Preview API — response shape may change.
• Slugs are the public ID on the character's page (venice.ai/c/); they are not the id UUID (though both resolve).
• isAdult is exclusive, not additive. You can't get adult and non-adult characters in one list call. If the account behind the key has the mature filter enabled, adult characters are never returned, even with isAdult=true.
• modelId filter vs. modelId field. For some models, filtering by the API model ID may return nothing even though characters built for that model exist — fall back to filtering data[].modelId client-side.
• modelId on a character is a suggestion. If you reuse it, it may be Pro-only, offline, or not an API model at all — handle 404 "Specified model not found", 401 "only available to Pro users" and 503 from chat and fall back to another model.
• photoUrl / shareUrl / description are typed nullable — don't assume they exist.