OPopensea
Account Endpoints

Upload a profile image

Changed on

Set imageType to profile_picture for the avatar or banner_image for the profile banner. Set contentType to the exact MIME type of the image bytes; it must be an image type such as image/png, image/jpeg, image/gif or image/webp. Files can be up to 50 MB; the storage upload rejects a larger file or a non-image Content-Type field. This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds. Pass the token in PATCH /api/v2/profile as profileImageToken for profile_picture or bannerImageToken for banner_image. Requires the write:profile scope.

post/api/v2/profile/images

Request

Request body

contentTypestring required

Exact MIME type of the image bytes. Must be an image/ type; anything else returns a 400.

imageType'profile_picture' | 'banner_image' required

Which profile image to upload: profile_picture (avatar) or banner_image. Case insensitive; any other value returns a 400.

Example request

{
  "contentType": "image/png",
  "imageType": "profile_picture"
}

Response

Upload context returned successfully

fieldsobject required

Short-lived sensitive multipart text fields for POST. Submit every entry unchanged before the file part. Content-Type contains the exact MIME type required by the signed policy. This map is empty for PUT.

method'POST' | 'PUT' required

HTTP method to use at url. Current upload contexts use POST.

tokenstring required

Reference for the next OpenSea API call. Use it only after storage returns 2xx.

urlstring required

Short-lived storage URL. Use it exactly as returned and treat it as sensitive.

Example response

{
  "fields": {
    "key": "uploads/example.png",
    "Content-Type": "image/png"
  },
  "method": "POST",
  "token": "upload-token-example",
  "url": "https://uploads.example.com/"
}

Changes

  • 2c7935d84f90Revision changes
    • breaking

      request property was restricted to a list of enum values

    • info

      added the new banner_image enum value to the request property

    • info

      added the new profile_picture enum value to the request property

    • info

      added the media type */* for the response with the status

    • info

      added the media type */* for the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status