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. |
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:
- 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;
- 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 |
| 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 |
|
|
| 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 |
| character_id |
1 |
string |
|
|
| 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_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 |
| 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 |
| 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 |
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). |
No fields.
| 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. |
| 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 |
|