Skip to content

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
Min: 1
Max: 100

  • Number of character models uploaded in a single request
  • The number of items in the data array may not match the count in the response. To determine if you have reached the last page, please check for the presence of links.next.href instead of relying on the number of items in the response.

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
Min: 1
Max: 100

  • Number of character models uploaded in a single request
  • The number of items in the data array may not match the count in the response. To determine if you have reached the last page, please check for the presence of links.next.href instead of relying on the number of items in the response.

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'

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"]

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
Min: 1
Max: 100

  • Number of character models uploaded in a single request
  • The number of items in the data array may not match the count in the response. To determine if you have reached the last page, please check for the presence of links.next.href instead of relying on the number of items in the response.

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
Min: 1
Max: 100

  • Number of character models uploaded in a single request
  • The number of items in the data array may not match the count in the response. To determine if you have reached the last page, please check for the presence of links.next.href instead of relying on the number of items in the response.

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: false

  • Determines whether it's a downloadable character model

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'

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"]