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
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
string
Form Data Parameters
object
object
string
string
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
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
string
Headers
string
Form Data Parameters
object
string
string
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}"
}
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
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
string
Headers
string
Form Data Parameters
object
object
string
string
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.
Last updated July 16, 2022 · Improve this page