venice-characters

Venice Characters

キャラクターはVeniceで公開されているペルソナです。それぞれにシステムプロンプト（任意のコンテキストを含む）、推奨バックエンドモデル、メタデータ（タグ、評価、成人向け／Webフラグ）がまとめられています。venice_parameters.character_slugでslugを渡すと、チャットにキャラクターを適用できます。

次の場合に使用します

• キャラクター選択UIやキャラクターを見つけるための画面を構築したい場合。
• プリセットのペルソナ（コーディングコーチ、哲学者、ゲームのNPCなど）を備えたアプリを提供したい場合。
• キャラクターに適したモデルを選びたい場合（キャラクターのmodelIdは候補です。チャットのmodelは自分で選択します）。

エンドポイントは3つあり、すべてプレビューとしてタグ付けされています（変更される可能性があります）。

エンドポイント	目的
GET /characters	カタログの閲覧／検索／絞り込み。
GET /characters/{slug}	キャラクターを1件取得。
GET /characters/{slug}/reviews	ページネーション対応の公開レビュー。

認証：Bearer APIキーのみ。 これらのルートはx402 / SIGN-IN-WITH-Xを受け付けません（SIWXのみのリクエストには401を返します）。Authorizationヘッダーのないリクエストには、401ではなくx402の検出チャレンジとして402を返します。未認証でのアクセスはできません。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, ...] }（合計件数はありません。limitより少ない件数が返されるまで、offsetを使ってページを取得してください）。

クエリパラメーター

パラメーター	型	注記
search	string、200文字以下	名前、説明、タグに対する大文字小文字を区別しない部分一致です。#Tagの語句はタグとの完全一致でも照合されます（#は%23としてURLエンコードしてください）。
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より優先されます。
isWebEnabled	"true" / "false"	trueはWeb対応のキャラクターのみを返します。falseは絞り込みを行いません。
sortBy	enum	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以上の評価が少なくとも1件あるキャラクターのみを作成日順に並べます。
• highestRating（平均評価）、ratingCount、imports、mostRecent（作成日）は並べ替えのみを行います。

Characterオブジェクト

フィールド	注記
id	UUID。
slug	チャットではこれをcharacter_slugとして使用してください。 venice.ai/c/<slug>の公開IDと同じです。
name, description	descriptionはnullの場合があります。
photoUrl, shareUrl	型付きのnullable値です。shareUrlはhttps://venice.ai/c/<slug>です（GET /characters/{slug}では、作者の?ref=紹介コードが含まれる場合もあります）。
author	作者に基づいて生成された5文字の匿名ID。
tags[]	タグ名。
featured, adult, webEnabled	ブール値。
modelId	キャラクター用に構築されたモデルIDです。通常はvenice-uncensored-1-2などのVenice APIモデルIDですが、/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 では、スラッグに対して次の処理が行われます。

• キャラクターのシステムプロンプト（およびキャラクターのコンテキストメッセージ）を会話の先頭に追加します。
• include_venice_system_promptのデフォルトはtrueです。キャラクターの声だけにしたい場合はfalseに設定します。カスタムのシステムプロンプトを設定したキャラクターでは、Venice のプロンプトは自動的に無効になります。
• 不明なスラッグ、または API で表示できないスラッグの場合は、404 "No character could be found from the provided character_slug"を返します。
• E2EE リクエストではキャラクターの挿入がスキップされます — E2EE モデルを E2EE ヘッダー付きで呼び出すと、スラッグは無視されます。同じモデルでも TEE のみのモード（E2EE ヘッダーなし、またはenable_e2ee: false）ではキャラクターが適用されます。

character_slugは/responsesのvenice_parametersでも受け付けられます。詳しくは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、200 文字を超えるsearch、配列項目が 20 個を超える場合）。
401	API キーが不明、期限切れ、または失効しているか、SIWX のみの認証です（ここではサポートされていません）。
402	Authorizationヘッダーがありません — x402 検出チャレンジです。Bearer キーを送信してください。
404	不明、未承認、または非表示のスラッグです（アカウントで成人向けフィルターが有効な場合の成人向けキャラクターも含みます）。
429	リクエストの失敗が多すぎます（エラーレート制限）。
500	一時的なエラーです。再試行してください。

注意点

• これはプレビュー APIです。レスポンスの形式は変更される場合があります。
• スラッグはキャラクターページ（venice.ai/c/<slug>）上の公開 IDです。id UUID ではありません（ただし、どちらも解決できます）。
• isAdult は排他的であり、追加指定ではありません。 1 回の一覧取得で、アダルトと非アダルトのキャラクターを両方取得することはできません。キーのアカウントで成熟コンテンツフィルターが有効になっている場合、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 は null 許容として型定義されています。存在するとは限りません。