venice-characters

Venice Characters

Characters 是 Venice 上已发布的人设——每个角色都包含一个系统提示词（以及可选的上下文）、建议使用的底层模型和元数据（标签、评分、成人 / 网络标记）。通过在 venice_parameters.character_slug 中传入角色的 slug，即可在聊天中应用该角色。

适用场景

• 想要构建角色选择 UI 或发现界面。
• 想要发布带有预设人设的应用（例如，编程教练、哲学家、游戏 NPC）。
• 想要为某个角色选择合适的模型（角色的 modelId 仅供参考；聊天使用的 model 由你选择）。

以下三个端点均标记为 Preview（可能会变更）：

端点	用途
GET /characters	浏览 / 搜索 / 筛选目录。
GET /characters/{slug}	获取单个角色。
GET /characters/{slug}/reviews	分页获取公开评价。

仅接受 Bearer API 密钥进行身份验证。 这些路由不接受 x402 / SIGN-IN-WITH-X（仅使用 SIWX 的请求会收到 401）。没有 Authorization 标头的请求会收到 402 x402 发现质询，而不是 401。不支持匿名访问。参见 venice-auth。

GET /characters

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

响应：{ "object": "list", "data": [Character, ...] }（不返回总数——使用 offset 分页，直到返回的条目少于 limit）。

查询参数

参数	类型	说明
search	string，≤ 200 个字符	对名称、描述或标签执行不区分大小写的子串匹配。#Tag 条件也会精确匹配标签（将 # URL 编码为 %23）。
categories	string[]，≤ 20 个（每个 ≤ 100 个字符）	重复传入该参数或使用逗号分隔。匹配任意一项。
tags	string[]，≤ 20 个（每个 ≤ 100 个字符）	重复传入或使用逗号分隔。精确匹配标签名称，匹配任意一项。
modelId	string[]，≤ 20 个（每个 ≤ 200 个字符）	按角色存储的模型 ID 筛选——参见注意事项。
isAdult	"true" / "false"	互斥筛选：true 仅返回成人角色；省略或设为 false 则仅返回非成人角色。
isPro	"true" / "false"	true = 仅返回模型在 Venice 应用中属于 Pro 模型的角色。false = 不筛选。与 modelId 同时传入时优先于 modelId。
isWebEnabled	"true" / "false"	true = 仅返回启用了网络功能的角色。false = 不筛选。
sortBy	枚举	featured、highestRating、highlyRated、highlyRatedAndRecent、imports、mostRecent、ratingCount。省略时 → 按导入次数从高到低排序。
sortOrder	asc / desc	默认值为 desc。仅在设置 sortBy 时生效。
limit	整数 1–100	默认值为 50。> 100 → 400。
offset	整数 ≥ 0	默认值为 0。

以下 sortBy 值还会筛选结果：

• featured — 仅包含精选角色，按导入次数排序。
• highlyRated — 仅包含评分数 ≥ 2 的角色，按平均评分排序。
• highlyRatedAndRecent — 仅包含至少有一个评分 ≥ 3 的角色，按创建日期排序。
• highestRating（平均评分）、ratingCount、imports、mostRecent（创建日期）仅排序。

Character 对象

字段	说明
id	UUID。
slug	在聊天中将其用作 character_slug。 与 venice.ai/c/<slug> 中的公开 ID 相同。
name、description	description 可能为 null。
photoUrl、shareUrl	类型为可空；shareUrl 为 https://venice.ai/c/<slug>（从 GET /characters/{slug} 获取时，也可能包含作者的 ?ref= 推荐码）。
author	根据作者生成的 5 个字符的匿名 ID。
tags[]	标签名称。
featured、adult、webEnabled	布尔值。
modelId	创建角色时使用的模型 ID——通常是 Venice API 模型 ID，例如 venice-uncensored-1-2，但也可能是 /models 未列出的 ID；如果角色未指定模型，则为 Venice 的默认聊天模型。
stats	{ averageRating, imports, ratingCount, ratingSum, userRating }。缺失的统计数据会以 0 返回；userRating 目前始终为 null。
createdAt、updatedAt	ISO-8601。

GET /characters/{slug}

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

返回 { "object": "character", "data": Character }。如果角色不存在、未获批准／不可通过 API 查看（你自己的角色除外），或者角色为成人内容且你的账户已开启成熟内容过滤，则返回 404。该路径也可通过角色的 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"

参数	说明
page	整数 ≥ 1。默认值为 1。
pageSize	整数 1–100。默认值为 20。

响应（按时间从新到旧；不包括隐藏的评价）：

{
  "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 是 1–5 的整数；message、locale、userAvatarUrl 可以为 null。由当前调用账户撰写的评价，其 isOwner 为 true。
• pagination.total 统计可见评价；summary.totalReviews 是角色的总评价数，因此两者可能不同。
• 响应还会设置 x-pagination-limit、x-pagination-page、x-pagination-total、x-pagination-total-pages 标头。

在聊天中使用角色

最简用法

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

Venice 对 slug 的处理方式：

• 将角色的系统提示词（以及任何角色上下文消息）添加到对话开头。
• include_venice_system_prompt 默认为 true；设为 false 即可使用纯粹的角色语气。配置了自定义系统提示词的角色会自动关闭 Venice 提示词。
• 未知或无法通过 API 查看的 slug → 404 "No character could be found from the provided character_slug"。
• E2EE 请求会跳过角色注入 —— 使用 E2EE 标头调用 E2EE 模型时，会静默忽略 slug。相同模型在仅 TEE 模式下（不带 E2EE 标头，或 enable_e2ee: false）则会应用角色。

在 /responses 的 venice_parameters 中也可以使用 character_slug —— 参见 venice-responses。

选择模型

请求中的 model 始终是实际运行的模型 —— Venice 不会切换到角色的 modelId。如果你想获得角色作者预期的体验，请使用角色的 modelId；如果需要该模型不具备的能力（函数调用、视觉、推理），则可使用其他聊天模型：

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

通过 model 字符串中的功能后缀指定

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

如果客户端库（OpenAI SDK、LangChain 等）无法添加 venice_parameters，这种方式会很有用。完整的后缀语法请参见 venice-chat。

使用模式

角色选择器 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: [...]
})

支持网页访问、适合家庭、近期且评价良好

/characters?isWebEnabled=true&sortBy=highlyRatedAndRecent

（默认已排除成人内容；isAdult=false 是多余的。）

按话题标签搜索

/characters?search=%23Philosophy

错误

代码	含义
400	查询参数无效（例如 limit > 100、pageSize > 100、未知的 sortBy、search 超过 200 个字符、数组项超过 20 个）。
401	API 密钥未知、已过期或已撤销，或仅使用 SIWX 身份验证（此处不支持）。
402	没有 Authorization 标头 —— x402 发现质询。请发送 Bearer 密钥。
404	未知／未获批准／隐藏的 slug（账户开启成熟内容过滤时，成人角色也会返回此错误）。
429	失败请求过多（错误率限制器）。
500	临时错误。请重试。

注意事项

• 这是一个 Preview API，响应结构可能会发生变化。
• Slug 是角色页面上的公开 ID（venice.ai/c/<slug>），不是 id UUID（不过两者都能解析）。
• isAdult 是排他性的，而非叠加性的。 你无法在一次列表调用中同时获取成人和非成人角色。如果密钥对应的账户启用了成熟内容过滤器，即使设置了 isAdult=true，也不会返回成人角色。
• modelId 过滤条件与 modelId 字段。 对于某些模型，按 API 模型 ID 过滤可能不会返回任何结果，即使存在为该模型构建的角色——此时可改为在客户端按 data[].modelId 过滤。
• 角色的 modelId 只是建议值。如果你复用它，该模型可能仅限 Pro 用户使用、处于离线状态，或者根本不是 API 模型——请处理聊天请求返回的 404 "Specified model not found"、401 "only available to Pro users" 和 503，并改用其他模型。
• photoUrl / shareUrl / description 的类型允许为空——不要假设这些字段一定存在。