--- title: "Sets the avatar to the incoming avatar using field masks." method: PATCH path: "/v4/avatar" tags: ["Avatars"] --- # Sets the avatar to the incoming avatar using field masks. `PATCH /v4/avatar` Only allows items that you own, are not expired, and are wearable asset types. Any assets being worn before this method is called are automatically removed. ## Headers - `Roblox-Place-Id` integer ## Request body - RobloxApiAvatarModelsV4RequestUpdateAvatarDefinitionRequestV4 — Request model for updating an avatar definition (V4). - `updateTypes` integer[] — The list of data needed to be updated. - `avatarDefinition` RobloxApiAvatarModelsV4UpdateAvatarDefinition — A model containing details about an avatar update. - `updateAvatarModel` RobloxApiAvatarModelsV4UpdateAvatarModelV4 — A model containing avatar model fields to update. - `scales` RobloxWebResponsesAvatarScaleModel - `height` number, double - `width` number, double - `head` number, double - `depth` number, double - `proportion` number, double - `bodyType` number, double - `playerAvatarType` 1 | 3 — The avatar type. - `bodyColors` RobloxApiAvatarModelsBodyColorsModelV4 — A model containing RGB hex colors for each body part. - `headColor` string — The RGB hex color for head color, e.g. #FFFFFF - `torsoColor` string — The RGB hex color for torso color, e.g. #FFFFFF - `rightArmColor` string — The RGB hex color for right arm color, e.g. #FFFFFF - `leftArmColor` string — The RGB hex color for left arm color, e.g. #FFFFFF - `rightLegColor` string — The RGB hex color for right leg color, e.g. #FFFFFF - `leftLegColor` string — The RGB hex color for left leg color, e.g. #FFFFFF - `assets` RobloxApiAvatarModelsAssetWearModel[] — The assets worn on the character. - `id` integer — An asset id - `meta` RobloxApiAvatarModelsAssetMetaModelV1 — Exhaustive model denoting all possible metadata fields of an asset - `order` integer — Layered-clothing order - `puffiness` number, float — Layered-clothing puffiness - `position` RobloxApiAvatarModelsAssetPosition — A model which contains accessory position coordinates. - `X` number, float — X coordinate of the position. - `Y` number, float — y coordinate of the position. - `Z` number, float — Z coordinate of the position. - `rotation` RobloxApiAvatarModelsAssetRotation — A model which contains accessory rotation coordinates. - `X` number, float — X degrees of the rotation. - `Y` number, float — Y degrees of the rotation. - `Z` number, float — Z degrees of the rotation. - `scale` RobloxApiAvatarModelsAssetScale — A model which contains accessory scale. - `X` number, float — X scale multiplier of accessory. - `Y` number, float — Y scale multiplier of accessory. - `Z` number, float — Z scale multiplier of accessory. - `headShape` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 — Head Shape selected for the asset id. Applicable for dynamic head assets. - `staticFacialAnimation` boolean — Indicates user choice for facial animation. staticFacialAnimation=false, implies the toggle as on and face will animate. Applicable for dynamic head assets. - `version` integer — Client-authoritative meta model format version - default is always 1 - `updateAvatarConfig` RobloxApiAvatarModelsV4UpdateAvatarConfig — A model containing avatar config fields to update. - `emoteRequestModels` RobloxApiAvatarModelsEmoteRequestModel[] — The avatar's emotes. - `assetId` integer — The asset id of the emote - `position` integer — The position to equip the emote to - `thumbnailCustomizationModels` RobloxApiAvatarModelsAvatarThumbnailCustomizationModel[] — The avatar's thumbnail customizations. - `thumbnailType` 0 | 1 | 2 — What type of 2D thumbnail are we customizing: |Closeup, FullBody. - `emoteAssetId` integer — What emote are we using to pose the avatar in the thumbnail. - `camera` RobloxApiAvatarModelsAvatarThumbnailCustomizationCameraModel — A model describing a the camera details for a single avatar thumbnail customization. - `fieldOfViewDeg` number, double — Field of view for the camera, in degrees. - `yRotDeg` number, double — Rotation around y axis, in degrees. - `distanceScale` number, double — There's a natural camera distance we calculate based on avatar size. Apply this scale to that distance. - `backgroundRequestModel` RobloxApiAvatarModelsV4AvatarBackgroundRequestModel — A model which contains the asset id of the background. This can be extended to have more attributes in the future. - `id` integer — An asset id. - `profileFrameRequestModel` RobloxApiAvatarModelsV4AvatarProfileFrameRequestModel — A model which contains the asset id of the profile frame. - `id` integer — An asset id. Use 0 to clear the equipped frame. ## Response `200` OK - RobloxApiAvatarModelsV4ResponseUpdateAvatarDefinitionResponseV4 — Response model for update avatar (V4). - `success` boolean — Whether all requested changes were successfully applied. - `invalidAssets` RobloxApiAvatarModelsAssetModelV2[] — Temporary top-level mirror of Roblox.Api.Avatar.Models.V4.Response.AvatarValidationResultV4.InvalidAssets to unblock clients that still read `invalidAssets` at the response root during backgrounds rollout. Prefer Roblox.Api.Avatar.Models.V4.Response.UpdateAvatarDefinitionResponseV4.Validation.Roblox.Api.Avatar.Models.V4.Response.AvatarValidationResultV4.InvalidAssets. Will be reverted once the engine fix is fully deployed. - `id` integer — The id - `name` string — The name - `assetType` RobloxApiAvatarModelsAssetTypeModel — A model containing details about an asset type - `id` integer — The id - `name` string — The name - `currentVersionId` integer — Id of the current version of asset - `meta` RobloxApiAvatarModelsAssetMetaModelV1 — Exhaustive model denoting all possible metadata fields of an asset - `order` integer — Layered-clothing order - `puffiness` number, float — Layered-clothing puffiness - `position` RobloxApiAvatarModelsAssetPosition — A model which contains accessory position coordinates. - `X` number, float — X coordinate of the position. - `Y` number, float — y coordinate of the position. - `Z` number, float — Z coordinate of the position. - `rotation` RobloxApiAvatarModelsAssetRotation — A model which contains accessory rotation coordinates. - `X` number, float — X degrees of the rotation. - `Y` number, float — Y degrees of the rotation. - `Z` number, float — Z degrees of the rotation. - `scale` RobloxApiAvatarModelsAssetScale — A model which contains accessory scale. - `X` number, float — X scale multiplier of accessory. - `Y` number, float — Y scale multiplier of accessory. - `Z` number, float — Z scale multiplier of accessory. - `headShape` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 — Head Shape selected for the asset id. Applicable for dynamic head assets. - `staticFacialAnimation` boolean — Indicates user choice for facial animation. staticFacialAnimation=false, implies the toggle as on and face will animate. Applicable for dynamic head assets. - `version` integer — Client-authoritative meta model format version - default is always 1 - `availabilityStatus` string — Asset availability status. - `expirationTime` string, date-time — For rental assets only. (Future) ownership expiration time of the asset. - `supportsHeadShapes` boolean — If the "Id" is swappable, applicable for DH assets. - `validation` RobloxApiAvatarModelsV4ResponseAvatarValidationResultV4 — Validation details for avatar mutation responses when one or more inputs could not be applied. - `invalidAssets` RobloxApiAvatarModelsAssetModelV2[] — Assets that could not be worn. - `id` integer — The id - `name` string — The name - `assetType` RobloxApiAvatarModelsAssetTypeModel — A model containing details about an asset type - `id` integer — The id - `name` string — The name - `currentVersionId` integer — Id of the current version of asset - `meta` RobloxApiAvatarModelsAssetMetaModelV1 — Exhaustive model denoting all possible metadata fields of an asset - `order` integer — Layered-clothing order - `puffiness` number, float — Layered-clothing puffiness - `position` RobloxApiAvatarModelsAssetPosition — A model which contains accessory position coordinates. - `X` number, float — X coordinate of the position. - `Y` number, float — y coordinate of the position. - `Z` number, float — Z coordinate of the position. - `rotation` RobloxApiAvatarModelsAssetRotation — A model which contains accessory rotation coordinates. - `X` number, float — X degrees of the rotation. - `Y` number, float — Y degrees of the rotation. - `Z` number, float — Z degrees of the rotation. - `scale` RobloxApiAvatarModelsAssetScale — A model which contains accessory scale. - `X` number, float — X scale multiplier of accessory. - `Y` number, float — Y scale multiplier of accessory. - `Z` number, float — Z scale multiplier of accessory. - `headShape` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 — Head Shape selected for the asset id. Applicable for dynamic head assets. - `staticFacialAnimation` boolean — Indicates user choice for facial animation. staticFacialAnimation=false, implies the toggle as on and face will animate. Applicable for dynamic head assets. - `version` integer — Client-authoritative meta model format version - default is always 1 - `availabilityStatus` string — Asset availability status. - `expirationTime` string, date-time — For rental assets only. (Future) ownership expiration time of the asset. - `supportsHeadShapes` boolean — If the "Id" is swappable, applicable for DH assets. - `invalidBackground` RobloxApiAvatarModelsInvalidBackgroundResponse[] — Background assets that could not be applied. - `BackgroundAssetId` integer — The asset id of the emote - `Error` string — The error associated with the background. - `invalidProfileFrame` RobloxApiAvatarModelsInvalidProfileFrameResponse[] — Profile frame assets that could not be applied. - `FrameAssetId` integer — The asset id of the profile frame. - `Error` string — The error associated with the profile frame. - `invalidEmotes` RobloxApiAvatarModelsInvalidEmoteResponseModel[] — Emotes that could not be equipped. - `assetId` integer — The asset id of the emote - `position` integer — The position the emote is equipped to - `error` string — The error occured while trying to equip this emote - `invalidThumbnailCustomizations` RobloxApiAvatarModelsV4ResponseInvalidThumbnailCustomizationResponse[] — Thumbnail customizations that could not be applied. - `ThumbnailCustomizationModel` RobloxApiAvatarModelsAvatarThumbnailCustomizationModel — A model describing a single avatar thumbnail customization. - `thumbnailType` 0 | 1 | 2 — What type of 2D thumbnail are we customizing: |Closeup, FullBody. - `emoteAssetId` integer — What emote are we using to pose the avatar in the thumbnail. - `camera` RobloxApiAvatarModelsAvatarThumbnailCustomizationCameraModel — A model describing a the camera details for a single avatar thumbnail customization. - `fieldOfViewDeg` number, double — Field of view for the camera, in degrees. - `yRotDeg` number, double — Rotation around y axis, in degrees. - `distanceScale` number, double — There's a natural camera distance we calculate based on avatar size. Apply this scale to that distance. - `Error` string — The error associated with the thumbnail customization ## Other responses - `400` — 3: Invalid assetId 5: Meta does not apply to specified asset type 7: Required meta is not provided for the specific asset type - `401` — 0: Authorization has been denied for this request. - `403` — 0: Token Validation Failed - `500` — 2: Failed to wear asset. --- [API](https://skmtc.net/roblox/apis/roblox-api.md) · [All operations](https://skmtc.net/roblox/apis/roblox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/roblox/roblox-api/revisions/1d2042bb1a48/schema)