6 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

GET /cloud/v2/users/{user_id}:generateThumbnail — openapi

Generate User Thumbnail

Generates and returns the URL for the user's avatar thumbnail.

This is a long-running operation: the response is an Operation object. Poll the operation using its returned path until done is true. A completed operation contains either response or error:

• If response is set, response.imageUri contains the thumbnail URL.
• If error is set, the thumbnail couldn't be generated and response is not set. error.code and error.message describe the reason.

Always check for error before reading response.imageUri. See Get User Thumbnail Generation Operation.

Endpoint

Method: GET

Path: /cloud/v2/users/{user_id}:generateThumbnail

Servers:

• https://apis.roblox.com

Parameters

[
  {
    "name": "user_id",
    "in": "path",
    "description": "The user ID.",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "size",
    "in": "query",
    "description": "Size of the generated thumbnail. The generated thumbnail will have `size *\r\nsize` dimension.\r\n            \r\nCurrently supported values:\r\n48, 50, 60, 75, 100, 110, 150, 180, 352, 420, 720\r\nDefault is 420.",
    "schema": {
      "type": "integer",
      "format": "int32",
      "default": 0
    }
  },
  {
    "name": "format",
    "in": "query",
    "description": "Specify the format of the generated thumbnail. Default is `PNG`.\r\n            \r\nPossible values:\r\n            \r\n  | Value | Description |\r\n  | --- | --- |\r\n  | FORMAT_UNSPECIFIED | Default UserThumbnail Format -- set to png |\r\n  | PNG | Generate thumbnail in `.png` format |\r\n  | JPEG | Generate thumbnail in `.jpg` format |",
    "schema": {
      "enum": [
        "FORMAT_UNSPECIFIED",
        "PNG",
        "JPEG"
      ],
      "type": "string",
      "description": "Define the format of the thumbnail.",
      "default": "FORMAT_UNSPECIFIED"
    }
  },
  {
    "name": "shape",
    "in": "query",
    "description": "Specify the shape of the thumbnail. Default is `ROUND` (circular).\r\n            \r\nPossible values:\r\n            \r\n  | Value | Description |\r\n  | --- | --- |\r\n  | SHAPE_UNSPECIFIED | Default UserThumbnail Shape -- set to round |\r\n  | ROUND | Generate thumbnail as a circle. |\r\n  | SQUARE | Generate thumbnail as a rectangle. |",
    "schema": {
      "enum": [
        "SHAPE_UNSPECIFIED",
        "ROUND",
        "SQUARE"
      ],
      "type": "string",
      "description": "Define the shape of the thumbnail.",
      "default": "SHAPE_UNSPECIFIED"
    }
  }
]

Responses

{
  "200": {
    "description": "Success",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OpenCloudUsers.Operation"
        }
      }
    }
  }
}

Authentication

{
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "securitySchemes": {
    "roblox-api-key": {
      "type": "apiKey",
      "description": "A configurable key that allows granular access to Roblox resources. See https://create.roblox.com/docs/cloud/auth/api-keys for more information.",
      "name": "x-api-key",
      "in": "header"
    },
    "roblox-legacy-cookie": {
      "type": "apiKey",
      "description": "A browser cookie that represents the identity of a Roblox user. DO NOT SHARE THIS. Sharing this will allow someone to log in as you and to steal your Robux and items. We do not recommend using cookies to call endpoints. When possible, use API keys with the x-api-key header or OAuth 2.0 instead for authentication.",
      "in": "cookie",
      "name": ".ROBLOSECURITY"
    },
    "roblox-oauth2": {
      "type": "oauth2",
      "description": "Build or authorize apps to access Roblox resources. See https://create.roblox.com/docs/cloud/auth/oauth2-overview for more information.",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://apis.roblox.com/oauth/v1/authorize",
          "tokenUrl": "https://apis.roblox.com/oauth/v1/token",
          "refreshUrl": "https://apis.roblox.com/oauth/v1/token",
          "scopes": {}
        }
      }
    }
  }
}

Related Schemas

• OpenCloudUsers.Operation

Complete Operation Definition

{
  "tags": [
    "Avatars",
    "Thumbnails",
    "Users"
  ],
  "summary": "Generate User Thumbnail",
  "description": "Generates and returns the URL for the user's avatar thumbnail.\r\n            \r\nThis is a long-running operation: the response is an `Operation` object.\r\nPoll the operation using its returned `path` until `done` is `true`. A\r\ncompleted operation contains either `response` or `error`:\r\n            \r\n- If `response` is set, `response.imageUri` contains the thumbnail URL.\r\n- If `error` is set, the thumbnail couldn't be generated and `response` is\r\n  not set. `error.code` and `error.message` describe the reason.\r\n            \r\nAlways check for `error` before reading `response.imageUri`. See\r\n[Get User Thumbnail Generation Operation](https://create.roblox.com/docs/cloud/reference/features/users#Cloud_GetUserThumbnailGenerationOperation).",
  "operationId": "Cloud_GenerateUserThumbnail",
  "parameters": [
    {
      "name": "user_id",
      "in": "path",
      "description": "The user ID.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "size",
      "in": "query",
      "description": "Size of the generated thumbnail. The generated thumbnail will have `size *\r\nsize` dimension.\r\n            \r\nCurrently supported values:\r\n48, 50, 60, 75, 100, 110, 150, 180, 352, 420, 720\r\nDefault is 420.",
      "schema": {
        "type": "integer",
        "format": "int32",
        "default": 0
      }
    },
    {
      "name": "format",
      "in": "query",
      "description": "Specify the format of the generated thumbnail. Default is `PNG`.\r\n            \r\nPossible values:\r\n            \r\n  | Value | Description |\r\n  | --- | --- |\r\n  | FORMAT_UNSPECIFIED | Default UserThumbnail Format -- set to png |\r\n  | PNG | Generate thumbnail in `.png` format |\r\n  | JPEG | Generate thumbnail in `.jpg` format |",
      "schema": {
        "enum": [
          "FORMAT_UNSPECIFIED",
          "PNG",
          "JPEG"
        ],
        "type": "string",
        "description": "Define the format of the thumbnail.",
        "default": "FORMAT_UNSPECIFIED"
      }
    },
    {
      "name": "shape",
      "in": "query",
      "description": "Specify the shape of the thumbnail. Default is `ROUND` (circular).\r\n            \r\nPossible values:\r\n            \r\n  | Value | Description |\r\n  | --- | --- |\r\n  | SHAPE_UNSPECIFIED | Default UserThumbnail Shape -- set to round |\r\n  | ROUND | Generate thumbnail as a circle. |\r\n  | SQUARE | Generate thumbnail as a rectangle. |",
      "schema": {
        "enum": [
          "SHAPE_UNSPECIFIED",
          "ROUND",
          "SQUARE"
        ],
        "type": "string",
        "description": "Define the shape of the thumbnail.",
        "default": "SHAPE_UNSPECIFIED"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/OpenCloudUsers.Operation"
          }
        }
      }
    }
  },
  "x-roblox-stability": "STABLE",
  "x-roblox-rate-limits": {
    "perApiKeyOwner": {
      "period": "MINUTE",
      "maxInPeriod": 1000
    },
    "perOauth2Authorization": {
      "period": "MINUTE",
      "maxInPeriod": 10
    }
  },
  "x-roblox-engine-usability": {
    "apiKeyWithHttpService": true
  },
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "externalDocs": {
    "url": "https://create.roblox.com/docs/cloud/reference/features/avatars#Cloud_GenerateUserThumbnail"
  }
}