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"
}
(DEPRECATED) Upload media as an attachment
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.rbLast updated December 14, 2022 · Improve this page