Acquire a list of character models, detail of a character, and account information

Type information

Character model type

typescript

type CharacterModelLicenseSerializer = {
  modification: 'default' | 'disallow' | 'allow';
  redistribution: 'default' | 'disallow' | 'allow';
  credit: 'default' | 'necessary' | 'unnecessary';
  characterization_allowed_user: 'default' | 'author' | 'everyone';
  sexual_expression: 'default' | 'disallow' | 'allow';
  violent_expression: 'default' | 'disallow' | 'allow';
  corporate_commercial_use: 'default' | 'disallow' | 'allow';
  personal_commercial_use: 'default' | 'disallow' | 'profit' | 'nonprofit';
};

type TagSerializer = {
  name: string;
  locale: string | null;
  en_name: string | null;
  ja_name: string | null;
};

type AgeLimitSerializer = {
  is_r18: boolean;
  is_r15: boolean;
  is_adult: boolean;
}

type CharacterSerializer = {
  user: UserSerializer;
  id: string;
  name: string;
  is_private: boolean;
  created_at: string;
  published_at: string | null;
};

type CharacterModelBoothItemSerializer = {
  booth_item_id: number;
  part_category: string | null;
};

type CharacterModelSerializer = {
  id: string;
  name: string | null;
  is_private: boolean;
  is_downloadable: boolean;
  is_comment_off: boolean;
  is_other_users_available: boolean;
  is_other_users_allow_viewer_preview: boolean;
  is_hearted: boolean;
  portrait_image: PortraitImageSerializer;
  full_body_image: FullBodyImageSerializer;
  license?: CharacterModelLicenseSerializer;
  created_at: string;
  heart_count: number;
  download_count: number;
  usage_count: number;
  view_count: number;
  published_at: string | null;
  tags: TagSerializer[];
  age_limit: AgeLimitSerializer;
  character: CharacterSerializer;
  latest_character_model_version?: CharacterModelVersionSerializer;
  character_model_booth_items: CharacterModelBoothItemSerializer[];
}

type TextFragmentSerializer = {
  type: 'plain' | 'url' | 'tag';
  body: string;
  normalized_body: string;
}

type MotionSerializer = {
  personality_name: string;
  name: string;
  url: string;
}

type PersonalitySerializer = {
  name: string;
  label: string;
  label_en: string;
  waiting_motion: MotionSerializer;
  appearing_motion: MotionSerializer;
  liked_motion: MotionSerializer;
  other_motions: MotionSerializer[];
}

type CharacterWebsiteSerializer = {
 id: string;
 url: string;
 service: string; 
}

type CharacterHeaderSerializer = {
  original: ImageSerializer;
}

type CharacterIconSerializer = {
  is_default_image: boolean;
  original: ImageSerializer;
}

type CharacterDetailSerializer = {
  character: CharacterSerializer;
  user_detail: UserDetailSerializer;
  description_fragments: TextFragmentSerializer[];
  websites: CharacterWebsiteSerializer[];
  header: CharacterHeaderSerializer;
  icon: CharacterIconSerializer;
  description: string;
}

type CharacterModelDetailSerializer = {
  character_model: CharacterModelSerializer;
  description_fragments: TextFragmentSerializer[];
  reply_count: number;
  status_id: string;
  description: string;
  ogp_image_url: string;
  personality: PersonalitySerializer;
  character_detail: CharacterDetailSerializer;
}

User type

typescript

type UserIconSerializer = {
  is_default_image: boolean;
  sq170: ImageSerializer;
  sq50: ImageSerializer;
};

type UserSerializer = {
  id: string;
  pixiv_user_id: string;
  name: string;
  icon: UserIconSerializer;
};

type UserRelationshipSerializer = {
  user_id: string;
  is_following: boolean;
  is_followed: boolean;
}

type UserDetailSerializer = {
  user: UserSerializer;
  description: string;
  description_fragments: TextFragmentSerializer[];
  following_count: number;
  follower_count: number;
  relationShip: UserRelationshipSerializer;
}

type AgeLimitSerializer = {
  is_r18: boolean;
  is_r15: boolean;
  is_adult: booelean;
}

type CurrentUserSerializer = {
  locale: string;
  account_sub_avatar_id: string;
  is_pixiv_status_complete: boolean;
  is_showable_on_pixiv: boolean;
  is_developer: boolean;
  is_user_privacy_policy_accepted: boolean;
  user_detail: UserDetailSerializer;
  age_limit: AgeLimitSerializer;
}

Image type

typescript

type ImageSerializer = {
  url: string;
  url2x: string | null;
  width: number;
  height: number;
};

type PortraitImageSerializer = {
  is_default_image: boolean;
  original: ImageSerializer;
  w600: ImageSerializer;
  w300: ImageSerializer;
  sq600: ImageSerializer;
  sq300: ImageSerializer;
  sq150: ImageSerializer;
};

type FullBodyImageSerializer = {
  is_default_image: boolean;
  original: ImageSerializer;
  w600: ImageSerializer;
  w300: ImageSerializer;
};

CharacterModelVerison (avatar file version info) type

typescript

type CharacterModelVersionSerializer = {
  id: string;
  created_at: string;
  spec_version: string | null;
  exporter_version: string | null;
  triangle_count: number;
  mesh_count: number;
  mesh_primitive_count: number;
  mesh_primitive_morph_count: number;
  material_count: number;
  texture_count: number;
  joint_count: number;
  is_vendor_forbidden_use_by_others: boolean;
  is_vendor_protected_download: boolean;
  is_vendor_forbidden_other_users_preview: boolean;
  original_file_size: number | null;
  vrm_meta: any;
  original_compressed_file_size: number | null;
  conversion_state?: ModelBasisConversionStateSerializer;
  vendor_specified_license?: VendorSpecifiedLicenseSerializer;
  attached_items?: AttachedItemSerializer[];
};

type ModelBasisConversionStateSerializer = {
  current_state: 'pending' | 'processing' | 'completed' | 'failed';
};

// License information given when uploading from the application
type VendorSpecifiedLicenseSerializer = {
  modification: 'default' | 'disallow' | 'allow';
  redistribution: 'default' | 'disallow' | 'allow';
  credit: 'default' | 'necessary' | 'unnecessary';
  characterization_allowed_user: 'default' | 'author' | 'everyone';
  sexual_expression: 'default' | 'disallow' | 'allow';
  violent_expression: 'default' | 'disallow' | 'allow';
  corporate_commercial_use: 'default' | 'disallow' | 'allow';
  personal_commercial_use: 'default' | 'disallow' | 'profit' | 'nonprofit';
};

// Information given when uploading from VRoidMobile
type AttachedItemSerializer = {
  item_display_name: string;
  category_type:
    | 'skin'
    | 'eyebrow'
    | 'nose'
    | 'mouth'
    | 'ear'
    | 'face_shape'
    | 'lip'
    | 'eye_surrounding'
    | 'eyeline'
    | 'eyelash'
    | 'iris'
    | 'eye_white'
    | 'eye_highlight'
    | 'base_hair'
    | 'all_hair'
    | 'hair_front'
    | 'hair_back'
    | 'whole_body'
    | 'head'
    | 'neck'
    | 'shoulder'
    | 'arm'
    | 'hand'
    | 'chest'
    | 'torso'
    | 'waist'
    | 'leg'
    | 'tops'
    | 'bottoms'
    | 'onepiece'
    | 'shoes'
    | 'inner'
    | 'socks'
    | 'neck_accessory'
    | 'arm_accessory'
    | 'safety'
    | 'cheek';
  downloadable: boolean;
  take_free: boolean;
  id: string;
  attached_item_coins: AttachedItemCoinSerializer[];
};

type AttachedItemCoinSerializer = {
  coin_type: 'apple' | 'google';
  price: number;
};

List of character models posted by the user

GET: /api/account/character_models

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Query parameter

max_id

Required: No
Type: string

The last ID from the character models uploaded. Used for paging

count

Required: No
Type: integer
Default: 20

Number of character models uploaded in a single request

publication

Required: No
Type: string

Set character model availability

Response

200

{
  "data": CharacterModelSerializer[],
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

400

["COMMON_INVALID_COUNT: count is too long"]

401

[
  "OAUTH_UNAUTHORIZED: OAuth unauthorized",
  "COMMON_SIGNED_IN_REQUIRED: signed in required"
]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

List of available character models liked by the user

GET: /api/hearts

Header

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Query parameter

application_id

Required: Yes
Type: string

Application ID (ClientID)

max_id

Required: No
Type: string

The last ID from the character models uploaded. Used for paging

count

Required: No
Type: integer
Default: 20

Number of character models uploaded in a single request

is_downloadable

Required: No
Type: boolean
Default: true

Determines whether it's a downloadable character model (for unapproved applications, always true ）

characterization_allowed_user

Required: No
Type: 'default' | 'author' | 'everyone'
Default: 'author', however, if the application setting "use as avatar" is set to "yes", always set to 'everyone'

Restrictions on the type of personality allowed for this model

violent_expression

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "use this model for violent expression" is set to "yes", always set to 'allow'

Is use of this model for violent expression allowed?

sexual_expression

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "use this model for sexual expression" is set to "yes", always set to 'allow'

Is use of this model for sexual expression allowed?

corporate_commercial_use

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "app type" is set to "corporate app", always set to 'allow'

Is use of this model for corporate commercial purposes allowed?

personal_commercial_use

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, the application setting for "commercial use" takes precedent

Is use of this model for personal commercial purposes allowed?

political_or_religious_usage

Setting: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow'

Is use of this model for political or religious purposes allowed? (Parameter based on VRM PUBLIC LICENSE 1.0)

antisocial_or_hate_usage

Setting: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow'

Is use of this model for antisocial or hate speech purposes allowed? (Parameter based on VRM PUBLIC LICENSE 1.0)

modification

Required: No
Type: 'default' | 'disallow' | 'allow_modification'
Default: 'disallow', however, if the application setting "modify model" is set to "yes", always set to 'allow_modification'

Is modification or redistribution of a modified version of this model allowed?

redistribution

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "redistribute model" is set to "yes", always set to 'allow'

Is redistribution of this model allowed?

credit

Required: No
Type: 'default' | 'necessary' | 'unnecessary'
Default: if the application setting "show model credits" is set to "no", then 'unnecessary'

Are credits necessary for this model?

has_booth_items

Required: No
Type: boolean
Default: false

Does this model have linked BOOTH items?

booth_part_categories[]

Required: No
Type: array[string]
Default: []

Specify a category of BOOTH item

Response

200

{
  "data": CharacterModelSerializer[],
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

400

["COMMON_INVALID_COUNT: count is too long"]

401

[
  "OAUTH_UNAUTHORIZED: OAuth unauthorized",
  "COMMON_SIGNED_IN_REQUIRED: signed in required"
]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

List of character models recommended by VRoid Hub staff

GET: /api/staff_picks

Header

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Query parameter

max_id

Required: No
Type: string

The last ID from the character models uploaded. Used for page

count.

Required: No
Type: integer
Default: 20

Number of character models uploaded in a single request

Response

200

{
  "data": CharacterModelSerializer[],
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

400

["COMMON_INVALID_COUNT: count is too long"]

401

["OAUTH_UNAUTHORIZED: OAuth unauthorized"]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

Search character models from VRoid Hub

GET: /api/search/character_models

Header

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Query parameter

keyword

Required: YES
Type: string

Keyword for searching

search_after[]

Required: No
Type: string

Used for paging. It is included in the links.next.href in the previous response.

count

Required: No
Type: integer
Default: 20

Number of character models uploaded in a single request

sort

Required: No
Type: string
Default: _score

The sorting type is specified below.
- _score : order by relevance score.
- first_published_at : order by first published time of the character model.

is_downloadable

Required: No
Type: boolean
Default: true

Determines whether it's a downloadable character model (for unapproved applications, always true ）

characterization_allowed_user

Required: No
Type: 'default' | 'author' | 'everyone'
Default: 'author', however, if the application setting "use as avatar" is set to "yes", always set to 'everyone'

Restrictions on the type of personality allowed for this model

violent_expression

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "use this model for violent expression" is set to "yes", always set to 'allow'

Is use of this model for violent expression allowed?

sexual_expression

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "use this model for sexual expression" is set to "yes", always set to 'allow'

Is use of this model for sexual expression allowed?

corporate_commercial_use

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "app type" is set to "corporate app", always set to 'allow'

Is use of this model for corporate commercial purposes allowed?

personal_commercial_use

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, the application setting for "commercial use" takes precedent

Is use of this model for personal commercial purposes allowed?

political_or_religious_usage

Setting: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow'

Is use of this model for political or religious purposes allowed? (Parameter based on VRM PUBLIC LICENSE 1.0)

antisocial_or_hate_usage

Setting: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow'

Is use of this model for antisocial or hate speech purposes allowed? (Parameter based on VRM PUBLIC LICENSE 1.0)

modification

Required: No
Type: 'default' | 'disallow' | 'allow_modification'
Default: 'disallow', however, if the application setting "modify model" is set to "yes", always set to 'allow_modification'

Is modification or redistribution of a modified version of this model allowed?

redistribution

Required: No
Type: 'default' | 'disallow' | 'allow'
Default: 'disallow', however, if the application setting "redistribute model" is set to "yes", always set to 'allow'

Is redistribution of this model allowed?

credit

Required: No
Type: 'default' | 'necessary' | 'unnecessary'
Default: if the application setting "show model credits" is set to "no", then 'unnecessary'

Are credits necessary for this model?

has_booth_items

Required: No
Type: boolean
Default: false

Does this model have linked BOOTH items?

booth_part_categories[]

Required: No
Type: array[string]
Default: []

Specify a category of BOOTH item

Response

200

{
  "data": CharacterModelSerializer[],
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

400

["COMMON_INVALID_COUNT: count is too long"]

401

[
  "OAUTH_UNAUTHORIZED: OAuth unauthorized",
  "COMMON_SIGNED_IN_REQUIRED: signed in required"
]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

Detailed information of a character model.

GET: /api/character_models/{id}

Header

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Response

200

{
  "data": CharacterModelDetailSerializer,
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

401

["OAUTH_UNAUTHORIZED: OAuth unauthorized"]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

404

["COMMON_NOT_FOUND: not found"]

Account information for logged-in user.

GET: /api/account

Header

X-Api-Version

Required: YES

This is the VRoid Hub API version. The current version is version 11.

Response

200

{
  "data": CurrentUserSerializer,
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "_links": {
    "next": {
      "href": "string"
    }
  },
  "rand": "string"
}

401

["OAUTH_UNAUTHORIZED: OAuth unauthorized"]

403

["OAUTH_FORBIDDEN: OAuth forbidden"]

Acquire a list of character models, detail of a character, and account information ​

Type information ​

Character model type ​

User type ​

Image type ​

CharacterModelVerison (avatar file version info) type ​

List of character models posted by the user ​

Header ​

Query parameter ​

Response ​

List of available character models liked by the user ​

Header ​

Query parameter ​

Response ​

List of character models recommended by VRoid Hub staff ​

Header ​

Query parameter ​

Response ​

Search character models from VRoid Hub ​

Header ​

Query parameter ​

Response ​

Detailed information of a character model. ​

Header ​

Response ​

Account information for logged-in user. ​

Header ​

Response ​

Acquire a list of character models, detail of a character, and account information

Type information

Character model type

User type

Image type

CharacterModelVerison (avatar file version info) type

List of character models posted by the user

Header

Query parameter

Response

List of available character models liked by the user

Header

Query parameter

Response

List of character models recommended by VRoid Hub staff

Header

Query parameter

Response

Search character models from VRoid Hub

Header

Query parameter

Response

Detailed information of a character model.

Header

Response

Account information for logged-in user.

Header

Response