Skip to content

voplica.api.character

The protobuf package voplica.api.character: 1 service, 71 messages and 2 enums, defined in voplica/api/character/character.proto.

Each method is called as POST https://api.voplica.com/voplica.api.character.CharacterService/<Method> with its request message as JSON and your API key (Authentication); a method marked Anonymous allowed also answers without one. See the JSON API.

Method Request Response Description
CreateCharacter CreateCharacterRequest CreateCharacterResponse
UpdateCharacter UpdateCharacterRequest UpdateCharacterResponse
UpdateCharacterPublishStatus UpdateCharacterPublishStatusRequest UpdateCharacterPublishStatusResponse
DeleteCharacter DeleteCharacterRequest DeleteCharacterResponse
GetCharacter GetCharacterRequest GetCharacterResponse Anonymous allowed.
GetMultiCharacters GetMultiCharactersRequest GetMultiCharactersResponse Anonymous allowed.
GetCharacterMetadata GetCharacterMetadataRequest GetCharacterMetadataResponse Anonymous allowed.
ListCharacters ListCharactersRequest ListCharactersResponse Anonymous allowed.
AttachDatasetToCharacter AttachDatasetToCharacterRequest AttachDatasetToCharacterResponse Add dataset to character
DetachDatasetFromCharacter DetachDatasetFromCharacterRequest DetachDatasetFromCharacterResponse Delete dataset from character
GetDatasetsForCharacter GetDatasetsForCharacterRequest GetDatasetsForCharacterResponse Anonymous allowed. Get datasets for character
AddCharacterPreviewAsset AddCharacterPreviewAssetRequest AddCharacterPreviewAssetResponse
DeleteCharacterPreviewAsset DeleteCharacterPreviewAssetRequest DeleteCharacterPreviewAssetResponse
GetCharacterPreviewAssets GetCharacterPreviewAssetsRequest GetCharacterPreviewAssetsResponse Anonymous allowed.
CreateCharacterLook CreateCharacterLookRequest CreateCharacterLookResponse Create a named look for a character. Maximum 50 looks per character.
UpdateCharacterLook UpdateCharacterLookRequest UpdateCharacterLookResponse
DeleteCharacterLook DeleteCharacterLookRequest DeleteCharacterLookResponse Delete a look: removes the look asset rows and the look, then re-resolves the character’s default look (a manually selected default that is deleted is cleared).
GetCharacterLook GetCharacterLookRequest GetCharacterLookResponse Anonymous allowed. Reads follow the CHARACTER’s visibility, exactly like GetCharacter / GetCharacterPreviewAssets: anonymous viewers of a public+published character can read its looks.
ListCharacterLooks ListCharacterLooksRequest ListCharacterLooksResponse Anonymous allowed.
AddCharacterLookAsset AddCharacterLookAssetRequest AddCharacterLookAssetResponse Attach an existing IMAGE_ASSET (owned by the character’s owner) to a look.
RemoveCharacterLookAsset RemoveCharacterLookAssetRequest RemoveCharacterLookAssetResponse
CreateCharacterLookDraft CreateCharacterLookDraftRequest CreateCharacterLookDraftResponse Character look DRAFTS - the resumable wizard session. ALL SEVEN are ANY_USER, reads included: a draft is private in-progress work, so unlike the look reads above it does NOT follow the character’s visibility. Reading a draft that is not yours answers exactly as reading one that does not exist (byte-identical NOT_FOUND) - see the anti-enumeration note on the messages.
CloneCharacterLookToDraft CloneCharacterLookToDraftRequest CloneCharacterLookToDraftResponse “Clone and Change” - a saved look re-opened as a fresh draft of the caller’s. Owner-only, and a foreign or unknown look answers the same NOT_FOUND every other draft RPC answers. See the request message for what is copied and what deliberately is not.
GetCharacterLookDraft GetCharacterLookDraftRequest GetCharacterLookDraftResponse
UpdateCharacterLookDraft UpdateCharacterLookDraftRequest UpdateCharacterLookDraftResponse
DeleteCharacterLookDraft DeleteCharacterLookDraftRequest DeleteCharacterLookDraftResponse
BindCharacterLookDraftToCharacter BindCharacterLookDraftToCharacterRequest BindCharacterLookDraftToCharacterResponse Give a character-less draft its character, once and in one direction. The wizard’s new-character run calls this at SAVE, between creating the character and creating the look.
ListCharacterLookDrafts ListCharacterLookDraftsRequest ListCharacterLookDraftsResponse Lists the CALLER’s drafts for a character (“continue building a look”), or - with an empty character_id - the caller’s CHARACTER-LESS drafts (“continue a new-character run”), or - with all_characters - EVERY draft of the caller, character-less and bound, in one list.
ListCharacterLookAssets ListCharacterLookAssetsRequest ListCharacterLookAssetsResponse Anonymous allowed.
Field Number Type Label Description
look_id 1 string
asset_id 2 string Must be an IMAGE_ASSET owned by the character’s owner.
asset_type 3 voplica.types.character.CharacterLookAssetType

No fields.

Field Number Type Label Description
character_id 1 string
preview_asset_id 2 string
Field Number Type Label Description
created_asset_id 1 string
Field Number Type Label Description
character_id 1 string
dataset_id 2 string

No fields.

Give a CHARACTER-LESS draft its character. ONCE-ONLY, in one direction: unbound -> bound. A bound draft can never be re-bound to a different character and can never be un-bound, because the work already recorded on it - approved views, iteration history, the anchor - was done FOR the identity the wizard is building, and moving that wholesale to another character would silently rewrite what somebody approved.

TWO OWNERSHIP PROOFS, checked in this order:

  1. the DRAFT must be the caller’s - a foreign or unknown draft answers the byte-identical NOT_FOUND every other draft RPC answers, BEFORE the character is looked at at all, so this RPC never becomes a way to ask about somebody else’s draft;
  2. the CHARACTER must exist and be the caller’s - a foreign character and a non-existent one answer identically, exactly as CreateCharacterLookDraft already answers them.

RETRY SAFETY: re-binding to the SAME character succeeds and changes nothing. That is not a hole in once-only - no state moves - and without it a lost response would strand the wizard permanently, since the alternative to a retry is a draft that can never be saved. Binding to a DIFFERENT character is FAILED_PRECONDITION.

Field Number Type Label Description
draft_id 1 string
character_id 2 string Must exist and be OWNED BY THE CALLER. Must not be empty: this RPC binds, it never unbinds.
Field Number Type Label Description
draft 1 voplica.types.character.CharacterLookDraft The bound draft, exactly as GetCharacterLookDraft would return it (no previews - this RPC takes no fetching options, same as Create and Update).
Field Number Type Label Description
default_preview_retriever 1 voplica.types.file.FilesRetriever optional If provided, the found file variant groups will be returned for the default preview asset (this serves BOTH Character.default_preview and the nested Character.default_look.default_preview – one retriever, mirroring the GenModel pattern)
Field Number Type Label Description
asset_retriever 1 voplica.types.file.FilesRetriever optional If provided, the found file variant groups will be returned as each asset’s asset_groups
Field Number Type Label Description
previews_retriever 1 voplica.types.file.FilesRetriever optional If provided, the found file variant groups will be returned as each draft’s anchor_preview, resolved with the OWNER’s access control (a draft is never resolved for anyone else).
include_character_name 2 bool true = each draft BOUND to a character carries that character’s name as character_name (absent for a character-less draft); false (the default) = no name is resolved.
Field Number Type Label Description
previews_retriever 1 voplica.types.file.FilesRetriever optional If provided, the found file variant groups will be returned as each look’s default_preview, resolved with the CHARACTER’s access control.

Mirrors voplica.api.ai.model.ModelVariantSelectionStrategy.

Field Number Type Label Description
use_look_id 1 string oneof strategy Look ID must belong to the updated character.
use_latest_look 2 google.protobuf.Empty oneof strategy Do not set the default look explicitly. Instead, always use the latest created look as the default.
Field Number Type Label Description
character 1 voplica.types.character.Character
metadata 2 voplica.types.character.CharacterMetadata optional
Field Number Type Label Description
look_id 1 string The look to clone. Must exist and belong to a character OWNED BY THE CALLER.
Field Number Type Label Description
draft 1 voplica.types.character.CharacterLookDraft The new draft, exactly as GetCharacterLookDraft would return it (no previews - this RPC takes no fetching options, same as Create, Update and Bind).
Field Number Type Label Description
character_id 1 string
source_look_id 2 string optional
sheet_type 3 voplica.types.character.CharacterSheetType Absent / UNSPECIFIED reads as CHARACTER_SHEET_TYPE_DEFAULT.
Field Number Type Label Description
draft 1 voplica.types.character.CharacterLookDraft
Field Number Type Label Description
character_id 1 string
name 2 string
look_prompt 3 string optional
mpa_rating 4 voplica.types.base.MPARating
sheet_type 5 voplica.types.character.CharacterSheetType Layout of the look’s composed sheet. Absent / UNSPECIFIED (0) is stored and read as DEFAULT - see voplica.types.character.CharacterSheetType.
anchor 6 voplica.types.file.FileReference optional
Field Number Type Label Description
look 1 voplica.types.character.CharacterLook
Field Number Type Label Description
name 1 string
gender 2 voplica.types.base.GenderType
description 3 string optional
visibility 4 voplica.types.base.VisibilityType
nsfw 5 bool If character is targeted towards nsfw content
Field Number Type Label Description
character_id 1 string
Field Number Type Label Description
draft_id 1 string

No fields.

Field Number Type Label Description
look_id 1 string

No fields.

Field Number Type Label Description
character_id 1 string
preview_asset_id 2 string

No fields.

Field Number Type Label Description
character_id 1 string

No fields.

Field Number Type Label Description
character_id 1 string
dataset_id 2 string

No fields.

Field Number Type Label Description
draft_id 1 string
fields_fetching_options 2 CharacterLookDraftFieldsFetchingOptions optional
Field Number Type Label Description
draft 1 voplica.types.character.CharacterLookDraft
Field Number Type Label Description
look_id 1 string
previews_retriever 2 voplica.types.file.FilesRetriever optional
Field Number Type Label Description
look 1 voplica.types.character.CharacterLook
Field Number Type Label Description
character_id 1 string
Field Number Type Label Description
character_metadata 1 voplica.types.character.CharacterMetadata
Field Number Type Label Description
character_id 1 string
asset_id_filter 2 string optional Optionally filter by asset_id. If not provided - all preview assets are returned.
previews_retriever 3 voplica.types.file.FilesRetriever optional Entity-scoped file retrieval (see voplica.types.file.FilesRetriever): if provided, the found file variant groups will be returned for each preview asset (or for the asset that matched asset_id_filter if provided), resolved with the CHARACTER’s access control — public+published characters’ previews (including video previews) are readable by anyone.
Field Number Type Label Description
all_previews 1 voplica.types.file.AssetFileVariantGroups repeated 0 to 10 images / videos for character preview Note: file_variant_groups are returned only if requested explicitly
Field Number Type Label Description
character_id 1 string oneof attribute
idempotency_key 2 string oneof attribute
fields_fetching_options 3 CharacterFieldsFetchingOptions optional
Field Number Type Label Description
character 1 voplica.types.character.Character
Field Number Type Label Description
character_id 1 string
Field Number Type Label Description
dataset_ids 1 string repeated
Field Number Type Label Description
character_ids 1 string repeated
fields_fetching_options 2 CharacterFieldsFetchingOptions optional
with_metadata 3 bool
Field Number Type Label Description
characters_data 1 CharacterWithMetadata repeated
Field Number Type Label Description
asset_type 1 voplica.types.character.CharacterLookAssetType optional
asset_id 2 string optional
Field Number Type Label Description
look_id 1 string
filters 2 ListCharacterLookAssetsFilters optional
limit 3 int64 Max amount of elements per page
sort 4 ListCharacterLookAssetsSorting How to sort results
fields_fetching_options 5 CharacterLookAssetsFetchingOptions optional Extra options for fields fetching
cursor 10 string optional to continue pagination use next_token with before = false to fetch the next page or prev_token with before = true to fetch the previous page.
before 11 bool Used only with cursor. If false it means fetch data after cursor. If true it means fetch data before cursor.
check_more_available 12 bool Check limit + 1 to know if there is more data available. By default it is false. Meaning that more_available flag won’t be returned.
Field Number Type Label Description
assets 1 voplica.types.character.CharacterLookAsset repeated
next_token 2 string optional Token to pass in the next query’s Pagination directive to go to the next page It will be missing if this request didn’t return any data (i.e. no more data available)
prev_token 3 string optional Token to pass in the next query’s Pagination directive to go to the previous page It will be missing if this request didn’t return any data (i.e. no more data available)
more_available 4 bool optional Returns if there is more data available (i.e. checks limit + 1). Returned only if check_more_available is set to true
Field Number Type Label Description
sort_key 1 CharacterLookAssetSortKey
asc_sort 2 bool
Field Number Type Label Description
state 1 voplica.types.character.CharacterLookDraftState optional Restrict to one lifecycle state - the “continue” surface passes IN_PROGRESS, since terminal drafts stay listable but are not resumable.

Keyset pagination is VERBATIM the ListCharacterLooks shape (limit 3 / cursor 10 / before 11 / check_more_available 12; next 2 / prev 3 / more 4) so every list surface on this service pages identically.

Field Number Type Label Description
character_id 1 string
filters 2 ListCharacterLookDraftsFilters optional
limit 3 int64 Max amount of elements per page
fields_fetching_options 4 CharacterLookDraftFieldsFetchingOptions optional Extra options for fields fetching
all_characters 5 bool true = EVERY draft of the CALLER: the character-less ones and every character’s, in one list, created_at newest first, the same keyset paging; character_id is ignored when set. The client shows each draft’s binding from CharacterLookDraft.character_id (empty = character-less). Send it with character_id empty; the filters and the fetching options apply as in the other modes (include_character_name names each bound draft’s character).
cursor 10 string optional to continue pagination use next_token with before = false to fetch the next page or prev_token with before = true to fetch the previous page.
before 11 bool Used only with cursor. If false it means fetch data after cursor. If true it means fetch data before cursor.
check_more_available 12 bool Check limit + 1 to know if there is more data available. By default it is false. Meaning that more_available flag won’t be returned.
Field Number Type Label Description
drafts 1 voplica.types.character.CharacterLookDraft repeated The CALLER’s drafts for that character - or the CALLER’s character-less drafts when the request carried an empty character_id, or EVERY draft of the CALLER when it carried all_characters - ordered by created_at (newest first). Never anyone else’s, regardless of the character’s visibility.
next_token 2 string optional Token to pass in the next query’s Pagination directive to go to the next page It will be missing if this request didn’t return any data (i.e. no more data available)
prev_token 3 string optional Token to pass in the next query’s Pagination directive to go to the previous page It will be missing if this request didn’t return any data (i.e. no more data available)
more_available 4 bool optional Returns if there is more data available (i.e. checks limit + 1). Returned only if check_more_available is set to true
Field Number Type Label Description
mpa_filter 1 MPAFilter optional
Field Number Type Label Description
character_id 1 string
filters 2 ListCharacterLooksFilters optional
limit 3 int64 Max amount of elements per page
fields_fetching_options 4 CharacterLookFieldsFetchingOptions optional Extra options for fields fetching
cursor 10 string optional to continue pagination use next_token with before = false to fetch the next page or prev_token with before = true to fetch the previous page.
before 11 bool Used only with cursor. If false it means fetch data after cursor. If true it means fetch data before cursor.
check_more_available 12 bool Check limit + 1 to know if there is more data available. By default it is false. Meaning that more_available flag won’t be returned.
Field Number Type Label Description
looks 1 voplica.types.character.CharacterLook repeated Ordered by created_at (newest first).
next_token 2 string optional Token to pass in the next query’s Pagination directive to go to the next page It will be missing if this request didn’t return any data (i.e. no more data available)
prev_token 3 string optional Token to pass in the next query’s Pagination directive to go to the previous page It will be missing if this request didn’t return any data (i.e. no more data available)
more_available 4 bool optional Returns if there is more data available (i.e. checks limit + 1). Returned only if check_more_available is set to true
Field Number Type Label Description
owner_id 1 string optional
visibility 2 voplica.types.base.VisibilityType optional This must be set to PUBLIC for the following cases: - When queried without owner_id. Permission denied will be returned otherwise. - When queried for other owner_id (i.e. not our Characters). Permission denied will be returned otherwise.
status 3 voplica.types.base.PublishStatus optional This must be set to PUBLISHED for the following cases: - When queried without owner_id. Permission denied will be returned otherwise. - When queried for other owner_id (i.e. not our Characters). Permission denied will be returned otherwise.
nsfw 4 bool optional true means to return NSFW characters only. false means to exclude NSFW characters. unset means to return both NSFW and SFW characters.
gender 5 voplica.types.base.GenderType optional Filter by gender
no_relation_filter 10 google.protobuf.Empty oneof relation Doesn’t apply any relation filters
tag 11 string oneof relation Filter by tag
query 12 string oneof relation Case-insensitive character NAME substring search (‘%term%’), composed with the other filters above. Server-side guards: blank after trim = no filter; 1 char after trim = INVALID_ARGUMENT (min 2 chars); capped at 100 chars. When set, results are ordered by created_at (keyset) regardless of the requested trending sort key — mirrors the Voices query relation semantics.
Field Number Type Label Description
filters 1 ListCharactersFilters optional
limit 2 int64 Max amount of elements per page
sort 3 ListCharactersSorting How to sort results
fields_fetching_options 4 CharacterFieldsFetchingOptions optional Extra options for fields fetching
cursor 10 string optional to continue pagination use next_token with before_cursor = false to fetch the next page or prev_token with before_cursor = true to fetch the previous page.
before 11 bool Used only with cursor. If false it means fetch data after cursor. If true it means fetch data before cursor.
check_more_available 12 bool Check limit + 1 to know if there is more data available By default is is false. Meaning that more_available flag won’t be returned. In this case, the only way to verify that there is any data available is to fetch the next page. Generally this should not be used for infinite scrolls, but can be used if we have buttons like next, previous.
Field Number Type Label Description
characters 1 voplica.types.character.Character repeated
next_token 2 string optional Token to pass in the next query’s Pagination directive to go to the next page It will be missing if this request didn’t return any data (i.e. no more data available) If it’s missing the last used cursor is essentially the next_token
prev_token 3 string optional Token to pass in the next query’s Pagination directive to go to the previous page It will be missing if this request didn’t return any data (i.e. no more data available) If it’s missing the last used cursor is essentially the prev_token
more_available 4 bool optional Returns if there is more data available (i.e. checks limit + 1). Returned only if check_more_available is set to true
Field Number Type Label Description
sort_key 1 CharacterSortKey
asc_sort 2 bool

Same shape as voplica.api.ai.dataset.MPAFilter (the platform has no shared filter type; each API package declares its own). MPA filtering follows the filter-driven safety model: the caller supplies the filter, the backend never branches on anonymity.

Field Number Type Label Description
max_mpa_rating 1 voplica.types.base.MPARating oneof filter Return looks with this mpa rating or below.
nsfw 2 bool oneof filter true means NSFW only (X or XXX). false means SFW only (G/PG/PG_13/R).
Field Number Type Label Description
look_id 1 string
asset_id 2 string
asset_type 3 voplica.types.character.CharacterLookAssetType optional

No fields.

Field Number Type Label Description
draft_id 1 string
anchor 2 voplica.types.file.FileReference optional
anchor_kind 3 voplica.types.character.CharacterLookDraftAnchorKind optional
approved_views 4 voplica.types.character.CharacterLookDraftApprovedView repeated
stage_history 5 voplica.types.character.CharacterLookDraftStageHistory repeated
sheet_type 6 voplica.types.character.CharacterSheetType optional
state 7 voplica.types.character.CharacterLookDraftState optional
replace_approved_views 8 bool approved_views / stage_history are repeated and therefore have no presence of their own. Set the matching flag to REPLACE that collection with what this request carries (including the empty list); leave it false to keep the stored collection untouched.
replace_stage_history 9 bool
name 10 string optional
anchor_model_id 11 string optional Absent = leave as it is; an EMPTY string CLEARS, the same convention name above uses.
edit_model_id 12 string optional
Field Number Type Label Description
draft 1 voplica.types.character.CharacterLookDraft
Field Number Type Label Description
look_id 1 string
name 2 string optional
look_prompt 3 string optional Empty string clears the look prompt (the character-level look_prompt then applies).
mpa_rating 4 voplica.types.base.MPARating optional
preview 5 voplica.types.file.AssetSelectionStrategy optional Same mechanism as the character default_preview: the asset must already be attached to the look.
sheet_type 6 voplica.types.character.CharacterSheetType optional OPTIONAL so an update can leave the stored layout alone: unlike the create request, an absent value here means “do not change”, NOT “DEFAULT”. Sending UNSPECIFIED (0) explicitly resets the look to DEFAULT - see voplica.types.character.CharacterSheetType.
Field Number Type Label Description
look 1 voplica.types.character.CharacterLook
Field Number Type Label Description
character_id 1 string
status 2 voplica.types.base.PublishStatus
Field Number Type Label Description
status 1 voplica.types.base.PublishStatus
Field Number Type Label Description
character_id 1 string
name 2 string optional
gender 3 voplica.types.base.GenderType optional
description 4 string optional
visibility 5 voplica.types.base.VisibilityType optional
models 6 voplica.types.character.CharacterModelSet optional Model assignments
personality 7 voplica.types.character.CharacterPersonality optional
default_preview 8 voplica.types.file.AssetSelectionStrategy optional
look_prompt 9 string optional
tags 10 voplica.types.base.StringArray optional
nsfw 11 bool optional
default_look 12 CharacterLookSelectionStrategy optional
Field Number Type Label Description
character 1 voplica.types.character.Character
Name Number Description
CHARACTER_LOOK_ASSET_SORT_KEY_UNSPECIFIED 0
ADDED_AT 1
Name Number Description
MODEL_SORT_KEY_UNSPECIFIED 0
CREATED_AT 1
TRENDING_SCORE 2