venice-characters
GitHub用于发现和使用Venice平台的公开角色（Persona）。支持通过API搜索、筛选和排序角色目录，获取特定角色详情及评价，并将角色应用到聊天完成请求中以实现预设人设交互。
Trigger Scenarios
Install
npx skills add sediman-agent/OpenSkynet --skill venice-characters -g -y
SKILL.md
Frontmatter
{
"name": "venice-characters",
"description": "Discover and use Venice public characters (persona-driven system prompts with a bound model). Covers GET \/characters (search\/filter\/sort), \/characters\/{slug}, \/characters\/{slug}\/reviews, the Character schema, 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, 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 internalidUUID. photoUrl/shareUrl/userAvatarUrlcan benull— don't assume they exist.- Character
modelIdmay be gated (Pro, beta). If you always reuse the character'smodelId, handle401 "only available to Pro users"gracefully. - Adult-flagged characters are omitted unless
isAdult=trueis explicitly passed.
Version History
- c9d8953 Current 2026-07-05 20:05
