media API methods

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

Upload media as an attachment (async) 

POST /api/v2/media HTTP/1.1

Creates a media attachment to be used with a new status. The full sized media will be processed asynchronously in the background for large uploads.

Returns: MediaAttachment, but without a URL
OAuth: User token + write:media
Version history:
3.1.3 - added
3.2.0 - add thumbnail parameter
4.0.0 - Smaller media formats (image) will be processed synchronously and return 200 instead of 202. Larger media formats (video, gifv, audio) will continue to be processed asynchronously and return 202.

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
file
required Object. The file to be attached, encoded using multipart form data. The file must have a MIME type.
thumbnail
Object. The custom thumbnail of the media to be attached, encoded 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. See Focal points for cropping media thumbnails for more information.

Response

200: OK

MediaAttachment was created successfully, and the full-size file was processed synchronously.

{
  "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",
  "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}
202: Accepted

MediaAttachment was created successfully, but the full-size file is still processing. Note that the MediaAttachment’s url will still be null, as the media is still being processed in the background. However, the preview_url should be available. Use GET /api/v1/media/:id to check the status of the media attachment.

{
  "id": "22348641",
  "type": "image",
  "url": null,
  "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}"
}
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"
}
500: Server error

Could not generate a thumbnail for the attachment

{
  "error": "Error processing thumbnail for uploaded media"
}

Get media attachment 

GET /api/v1/media/:id HTTP/1.1

Get a media attachment, before it is attached to a status and posted, but after it is accepted for processing. Use this method to check that the full-sized media has finished processing.

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

Request

Path parameters
:id
required String. The ID of the MediaAttachment in the database.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

The media file was processed, and a url to the processed media is available.

{
  "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: Partial content

The media attachment is still being processed

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

MediaAttachment is not owned by you or does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity

There was an error processing the media attachment

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

Update media attachment 

PUT /api/v1/media/:id HTTP/1.1

Update a MediaAttachment’s parameters, before it is attached to a status and posted.

Returns: MediaAttachment
OAuth: User token + write:media
Version history:
0.0.0 - added
2.3.0 - add focus parameter
3.2.0 - added thumbnail

Request

Path parameters
:id
required String. The ID of the MediaAttachment in the database.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
thumbnail
Object. The custom thumbnail of the media to be attached, encoded 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. See Focal points for cropping media thumbnails for more information.

Response

200: OK

Attachment with an updated description

{
  "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 is not owned by you or does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity 
{
  "error": "Validation failed: File content type is invalid, File is invalid"
}

Upload media as an attachment (v1) deprecated 

POST /api/v1/media HTTP/1.1

Creates an attachment to be used with a new status. This method will return after the full sized media is done processing.

Returns: MediaAttachment
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. This is 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 Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
file
required Object. The file to be attached, encoded using multipart form data. The file must have a MIME type.
thumbnail
Object. The custom thumbnail of the media to be attached, encoded 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. See Focal points for cropping media thumbnails for more information.

Response

200: OK

Attachment created successfully. Note that the MediaAttachment will be created even if the file is not understood correctly due to failed processing.

Sample response for a correct file:

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

Sample response for an incorrect file, which results in a “missing” url:

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

See also

GET /api/v2/instance (for obtaining configuration limits)
Instance#configuration[media_attachments]
Focal points for cropping media thumbnails
app/controllers/api/v1/media_controller.rb
app/controllers/api/v2/media_controller.rb

Last updated October 10, 2024 · Improve this page