media

Attach media to authored statuses. See Using Mastodon > Posting toots > Attachments for more information about size and format limits.

Upload media as attachment

POST https://mastodon.example/api/v1/media

Creates an attachment to be used with a new status. Returns: Attachment OAuth: User token + write:media Version history: 0.0.0 - added 2.3.0 - add focus parameter

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
file	object	The file to be attached, using multipart form data.
description	string	A plain-text description of the media, for accessibility purposes.
focus	string	Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0

200 Attachment created successfully. Note that the Attachment will be created even if the file is not understood correctly.

file correct

{
  "id": "22348641",
  "type": "image",
  "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/cebc6d51be03e509.jpeg",
  "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg",
  "remote_url": null,
  "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ",
  "meta": {
    "focus": {
      "x": -0.69,
      "y": 0.42
    },
    "original": {
      "width": 640,
      "height": 480,
      "size": "640x480",
      "aspect": 1.3333333333333333
    },
    "small": {
      "width": 461,
      "height": 346,
      "size": "461x346",
      "aspect": 1.3323699421965318
    }
  },
  "description": "test uploaded via api",
  "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}

file not correct

401 Invalid or missing Authorization header

422 File or file type is unsupported or invalid

Update attachment

PUT https://mastodon.example/api/v1/media/:id

Update an Attachment, before it is attached to a status and posted. Returns: Attachment OAuth: User token + write:media Version history: 0.0.0 - added

Path Parameters

Name	Type	Description
:id	string	The id of the Attachment entity to be updated

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
file	object	The file to be attached, using multipart form data.
description	string	A plain-text description of the media, for accessibility purposes.
focus	string	Two floating points (x,y), comma-delimited ranging from -1.0 to 1.0

200

{
  "id": "22348641",
  "type": "image",
  "url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg",
  "preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg",
  "remote_url": null,
  "text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ",
  "meta": {
    "focus": {
      "x": -0.42,
      "y": 0.69
    },
    "original": {
      "width": 640,
      "height": 480,
      "size": "640x480",
      "aspect": 1.3333333333333333
    },
    "small": {
      "width": 461,
      "height": 346,
      "size": "461x346",
      "aspect": 1.3323699421965318
    }
  },
  "description": "test uploaded via api, but updated",
  "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}

401 Invalid or missing Authorization header

404 Attachment does not exist, is deleted, or was not created by you

422 File or file type is unsupported or invalid

Focal points

Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. See this guide on how focal points are defined. In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9.

A demonstration of various focal points and their coordinates.

A demonstration of various focal points and their coordinates.