3628b6d434
* add rules * join date on profiles * deprecate follow scope * deprecate identity proofs * familiar followers * use definition lists instead of tables for defining activitypub properties * reformat notifications page into markdown * fix broken links to publicKey header * Application website is now nullable * update environment variables added and removed * fix typo * fix heading level * min_id and max_id can be used at the same time (3.3) * fix typo * new tootctl options * reformat tootctl page to use definition lists for params * add rules and configuration to Instance * fix typo * refactor instance api page * 3.3.0 duration on mutes * 3.3.0 mute_expires_at * improve section headings * 3.4.0 resend email confirmation api * 3.4.0 policy on push subscriptions * 3.4.0 add details to account registration error * refactor accounts api page and start adding relrefs to entity pages * 3.4.0 accounts/lookup api * add see also to accounts methods * add more see-also links * 3.5.0 appeal mod decisions * 3.5.0 reformat reports and add category/rule_ids params * document report entity and missing responses * fix typos * fix relrefs and url schema, add aliases to old urls * add archetypes for new methods/entities * update archetypes with see-also stubs * clearer presentation of rate limits * announcements api methods * refactor apps methods * refactor bookmarks methods + some anchors * refactor conversations methods * custom_emojis methods refactor * anchors * refactor directory methods * refactor domain_blocks methods * add see also to emails methods * fix page relref shortcodes to specific methods + refactor endorsements methods * min_id max_id * refactor favourites methods * refactor featured_tags methods * refactor filters methods, make path params consistent, i18n required shortcode * follow_requests methods * lists methods * markers methods * forgot to add entity links * media methods, also fix formatting of some json errors * mutes methods, add more see-also links * oembed methods * preferences methods * proofs methods * push methods * suggestions methods * 3.5.0 add new trend types, fix formatting * refactor streaming methods * refactor oauth methods * note that streaming api casts payload to string * refactor search methods * refactor polls methods * remove unnecessary link * reformat scheduled_statuses methods * reformat timelines methods * reformat statuses methods * 3.5.0 editing statuses * consistent use of array brackets in form data parameters * update dev setup guide, add vagrant and clean up text * add admin/accounts methods * 3.6 role entity * admin/accounts methods v2 * minor fix * stub admin/reports methods * document admin reports * add 403 example to methods archetype * cleanup entities for admin reports and add new attrs * 3.6.0 domain allows methods + normalize admin entity namespace * fix search-and-replace error * add aliases for admin entities * 3.6.0 canonical email blocks entity * 3.5.0 admin/retention api * 3.5.0 add admin::ip doc * 3.5.0 admin/reports * 3.6.0 admin/domain_allows * 3.5.0 admin/dimensions * 3.6.0 permissions and roles * minor formatting fix * add anchor link to headings * checkpoint * add update commands to dev env setup guide * change mentions of v3.6 to v4.0 * tootctl now uses custom roles * fix formatting * v2 instance api * update frontmatter, add better titles to pages * minor wording change * consistency * add more aliases * add placeholders and WIP notices * explain link pagination and stub out todos * switch baseURL to https * 422 on reports with rules but category!=violation * document bug fixes * fix typo * remove duplicate API method definition * s/tootsuite/mastodon for github links * remove unnecessary escaping * s/tootsuite/mastodon in Entity archetype * add missing nullable shortcode * clarify oauth scope when requesting a user token * api/v2/media now synchronous for images * DISALLOW_UNAUTHENTICATED_API_ACCESS * add undocumented env variables * add instance domain blocks and extended description api * add SMTP_ENABLE_STARTTLS * add description to SMTP_ENABLE_STARTTLS * take suggestions from open PRs * normalize links and flavour language * Fully document streaming API based on source code * Add mention of MIME types * bump to ruby 3.0.4 * clarify how to check on async media processing * validation of replies_policy * remove TODOs on admin account action * EmailDomainBlocks * IpBlocks * Admin::DomainBlock * remove TODOs * following hashtags * followed_tags * remove reference to unused parameter * add new oauth scopes for admin blocks and allows * fix command signature for i18n-tasks normalize * reformat code structure page * document fixes for following tags (assume 4.0.3) * Add warning about pre-4.0 hardcoded roles * add note about case sensitivity * remove use of 'simply' from docs * remove reference to silencing * add reference to IDN normalization for verified links * add lang parameter
12 KiB
| title | description | menu | aliases | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 https://mastodon.example/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]({{< relref "entities/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
- {{}} Provide this header with
Bearer <user token>to gain authorized access to this API method.
Form data parameters
- file
- {{}} 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]({{< relref "api/guidelines#focal-points" >}}) 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 https://mastodon.example/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]({{< relref "entities/MediaAttachment" >}})
OAuth: User token + write:media
Version history:
3.1.3 - added
Request
Path parameters
- :id
- {{}} String. The ID of the MediaAttachment in the database.
Headers
- Authorization
- {{}} 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 https://mastodon.example/api/v1/media/:id HTTP/1.1
Update a MediaAttachment's parameters, before it is attached to a status and posted.
Returns: [MediaAttachment]({{< relref "entities/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
- {{}} String. The ID of the MediaAttachment in the database.
Headers
- Authorization
- {{}} 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]({{< relref "api/guidelines#focal-points" >}}) 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 https://mastodon.example/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]({{< relref "entities/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
- {{}} Provide this header with
Bearer <user token>to gain authorized access to this API method.
Form data parameters
- file
- {{}} 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]({{< relref "api/guidelines#focal-points" >}}) 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
{{< page-relref ref="methods/instance" caption="GET /api/v2/instance (for obtaining configuration limits)">}}
{{< page-relref ref="entities/instance#media_attachments" caption="Instance#configuration[media_attachments]">}}
{{< page-relref ref="api/guidelines#focal-points" caption="Focal points for cropping media thumbnails" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/media_controller.rb" caption="app/controllers/api/v1/media_controller.rb" >}}
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/media_controller.rb" caption="app/controllers/api/v2/media_controller.rb" >}}