media

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

post
Upload media as attachment

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
3.1.3 - deprecated in favor of POST /api/v2/media, which is equal to v1 in all aspects, except it returns HTTP 202, and the returned JSON object has a url of null, because while the thumbnail is prepared synchronously, the full version of the media attachment will be processed in the background
3.2.0 - add thumbnail parameter

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
file
required
object
The file to be attached, using multipart form data.
thumbnail
optional
object
The custom thumbnail of the media to be attached, using multipart form data.
description
optional
string
A plain-text description of the media, for accessibility purposes.
focus
optional
string
Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0

Response

200: Success

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
{
  "id": "22348456",
  "type": "unknown",
  "url": "https://mastodon.social/files/original/missing.png",
  "preview_url": "https://mastodon.social/files/small/missing.png",
  "remote_url": null,
  "text_url": "https://mastodon.social/media/Ao2nvQoQNHROpKgEyoA",
  "meta": {
    "focus": {
      "x": -0.69,
      "y": 0.42
    }
  },
  "description": "test uploaded via api",
  "blurhash": null
}

401: Unauthorized

Invalid or missing Authorization header 

{
  "error": "The access token is invalid"
}

422: Unprocessable Entity

File or file type is unsupported or invalid 

{
  "error": "Validation failed: File content type is invalid, File is invalid"
}

get
Update attachment

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

Get an Attachment, before it is attached to a status and posted, but after it is accepted for processing.

Returns: Attachment
OAuth: User token + write:media
Version history:
3.1.3 - added

Request

Path Parameters
:id
required
string
The id of the Attachment entity to be updated
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
file
optional
object
The file to be attached, using multipart form data.
description
optional
string
A plain-text description of the media, for accessibility purposes.
focus
optional
string
Two floating points (x,y), comma-delimited ranging from -1.0 to 1.0

Response

200: Success
Attachment has been processed 

{
  "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}"
}

206:

Attachment is not yet ready

401: Unauthorized

Invalid or missing Authorization header 

{
  "error": "The access token is invalid"
}

404: Not Found

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

{
  "error": "Record not found"
}

422: Unprocessable Entity

Error processing the media attachment 

{
  "error": "Validation failed: File content type is invalid, File is invalid"
}

put
Update attachment

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
3.2.0 - added thumbnail

Request

Path Parameters
:id
required
string
The id of the Attachment entity to be updated
Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
file
optional
object
The file to be attached, using multipart form data.
thumbnail
optional
object
The custom thumbnail of the media to be attached, using multipart form data.
description
optional
string
A plain-text description of the media, for accessibility purposes.
focus
optional
string
Two floating points (x,y), comma-delimited ranging from -1.0 to 1.0

Response

200: Success 

{
  "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: Unauthorized

Invalid or missing Authorization header 

{
  "error": "The access token is invalid"
}

404: Not Found

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

{
  "error": "Record not found"
}

422: Unprocessable Entity

File or file type is unsupported or invalid 

{
  "error": "Validation failed: File content type is invalid, File is 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.

Last updated December 27, 2020 · Improve this page