Media Upload Endpoint and Remote Media Library

[Jiwoon-Kim]

This post expands on some ideas mentioned in [#2314 – Add Attachments processor class for handling ActivityPub media](#2314), particularly around how remote vs. local media handling should work in WordPress.

---

1. Background

Recent improvements such as smart media markup and inline image handling have raised an important architectural question:
How should ActivityPub attachments (media objects) be handled differently from direct media file links?

Platforms like Mastodon cache all attachments locally, but WordPress operates with a Media Library, which introduces a fundamentally different model.
Therefore, the optimal approach may depend on the object type (e.g., Article vs. Note) and the presence of a media library endpoint.

---

2. Key distinctions

Media file direct links

• Represent one-time use links to files (usually hotlinked).
• Cannot be proven to be the same object across federated systems.
• Should remain as remote URLs rather than being imported into the Media Library.

Media objects

• Represent structured, reusable entities that imply the existence of a Media Library and an Upload Endpoint.
• May require an endpoint such as ?remote_attachment_id=123 for access and federation.
• Are ideal for inclusion of JSON-LD representations via the attachment page.

---

3. Proposed workflow

1. Load attachment JSON-LD metadata first.
   Then apply lazy loading for inline images or gallery blocks based on viewport size.

2. Implement remote media objects as hotlinks by default.
   The content of a remote image object remains a hotlink unless explicit reuse permission (license) is declared.

3. Optional local caching with license extension.
   If a [FEP-c118 Content Licensing](https://codeberg.org/fediverse/fep/src/branch/main/fep/c118/fep-c118.md) policy is detected, the system may:

   • Cache the file locally.
   • Replace the file URL with a local one.
   • Preserve the original URI for attribution.

4. Remote attachment persistence.
   Remote media attachment pages can remain even after the original post is deleted, since they may be reused or referenced via the media library.

---

4. Inline images and multiple versions

According to [FEP-b2b8: Long-form Text](https://codeberg.org/fediverse/fep/src/branch/main/fep/b2b8/fep-b2b8.md#content),

Any embedded media in the content property should also be listed in the attachment property.

However, WordPress’s Gutenberg system often uses gallery blocks with multiple image versions.
This makes simple inline-image models insufficient.
A better approach could follow the principles of [FEP-1311](https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md) (multiple media versions) and [FEP-e232](https://codeberg.org/fediverse/fep/src/branch/main/fep/e232/fep-e232.md) (object links).

For performance, Articles might reference a container URI (improved attachment_id permalink) that serves all image versions.

---

5. Relation to core proposals

• Improving the Permalink Structure for ?attachment_id=123
• [Media Library Improvements](https://make.wordpress.org/core/2023/07/07/media-library/)
• [AI: Building Blocks – Media Library](https://make.wordpress.org/ai/2025/07/17/ai-building-blocks/)

These efforts align naturally with the goal of introducing a Remote Media Library and Media Upload Endpoint for federated environments.

---

6. Conclusion

In summary:

• Media file direct links and media objects should be clearly separated.
• The attachment page is the best place for JSON-LD representation of media objects.
• Hotlink-first behavior improves performance, while license-based local caching supports proper attribution and reuse.
• Future extensions could allow federated commenting (inReplyTo) on remote media attachment pages once the underlying endpoint exists.

I’ll continue exploring this idea under the title “Media Upload Endpoint and Remote Media Library.”

[Jiwoon-Kim]

Media Upload Endpoint and Remote Media Library

Smart media markup: Generates blocks (or shortcodes) with gallery support for multiple images
4. The current version does not side-load inline images. I think we should support inline images and ignore attachments that reference the same one.

The appropriate approach may vary depending on the object type,
so direct image file links and image objects may require different attachment fetching behavior.

My current idea is to first load the JSON-LD metadata of all attachment objects, then render the appropriate image size version according to the viewport value, applying lazy loading to inline images or gallery blocks within the content field.
This way, better performance and flexibility can be provided without local uploads.

To implement inline images in the content field of an article, an extension of the HTML markup language is required.
In fact, even now, in wp-to-wp cases, when an ActivityPub object is embedded, the Gutenberg gallery block works. However, you cannot comment on the image carousel.
If a remote WordPress instance queries the remote media library through the media upload endpoint and stores the remote image object in ?remote_attachment_id, then when commenting, it becomes possible to federate replies to the remote attachment page (image object). After implementing this, if an official FEP extension is later added, it will enable other CMSs to post federated comments on attachment pages as well.

Remote URL support: Downloads and imports media from ActivityPub network

Metadata preservation: Stores source URLs and alt text for images

We should not add external Attachments to the Media-Library. This is very spammy and floods the internal media handling with external media.

Yes, I know that Mastodon caches all attachment images locally, but WordPress operates on a very different architecture.
There is a difference between platforms that have a media library and those that don’t.

If there is no media library, implementing the media object endpoint will be difficult, so the existence of a media object can be assumed to mean that a media library and media upload endpoint exist.
If a media object exists, it can be reused. However, in the case of a direct media file link, it cannot be proven in ActivityPub that it is the same entity, so it is one-time. Therefore, in the case of WordPress, there is no reason to store such media locally.

My opinion is that for this reason, media file direct links and media objects should be clearly distinguished. The attachment page is the ideal location because it includes the JSON-LD representation of the media object.

For platforms that have a media library,
a page such as ?remote_attachment_id may be required.
Such pages are created only for media objects.

In fact, most microblogging platforms in the Fediverse do not have media libraries.
Therefore, platforms like Mastodon, Pixelfed, and Threads attach direct media file links in the attachments field.
For directly attached media files, ?remote_attachment_id pages are not generated.

In both cases, I think the default behavior should maintain hotlinking (remote connections).

I think the content of a remote image object should basically maintain a hotlink.
Depending on the implementation, it is also possible to record it only in the database and use it without uploading the file itself to local storage.

When license extensions are applied, files are optionally cached locally, and the file URL is replaced with a local URL only when explicit reuse permission is granted, but the original URI is preserved.
https://codeberg.org/fediverse/fep/src/branch/main/fep/c118/fep-c118.md
FEP-c118: Content licensing support

2. When I delete a post, the Media-Attachment will not be deleted with the post.

The fact that remote media attachments remain even after the remote article is deleted is normal, because it means the media can continue to be reused through the media library.

• Local file support: Processes files from Mastodon archive imports

https://fedi.tips/how-to-download-your-mastodon-post-archive/
I looked up what Mastodon archive imports are, but they don’t seem to be related to federation.
I think local file support should be solved by improving media library behavior.

---

Additional reference materials

#2146 (comment)
"Shared media library between instances"

#2145
Improvements: The ActivityPub Object Representation for media attachment posts is missing. #2145

https://make.wordpress.org/core/2023/07/07/media-library/

On the management side, it’s time to look at categorization and tagging, better handling of attached media, design improvements to the library views and filtering. Several important functionalities are already present but not presented in the best way. For example, media attachment functionality (items anchored to a specific post) is often hard to discover, the interface is not the most intuitive, and the connection doesn’t necessarily carry through other editing flows in a clear way. For larger teams, media ingestion can often be an entirely separate process from writing posts. The ability to bulk attach media files and connect them to the relevant content pieces is thus an important part of the collaborative process.

When managing the media library, it should be easy to check and keep track of attribution. As we look into expanding the presence and touch points of [Openverse](https://openverse.org/), it’d be interesting to see how contributions to the commons could work directly from a user’s WordPress install. Another area to look at is improving handling and presentation of other media types (audio, video, files) and their connection with blocks and the block APIs. We should resurface work on a native Playlist block, ideally powered by the [Interactivity API](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/).

Finally, we should take a look at the publishing flows for media and format driven posts (where only one block type is present) to allow more expressive freedom.

https://make.wordpress.org/ai/2025/07/17/ai-building-blocks/

Media Library
Using AI to create and edit media is becoming increasingly popular. Additionally, there are many smaller implementations that AI could help with: auto alt text and captioning, intelligent grouping, multimodal search capabilities, and more.

https://core.trac.wordpress.org/ticket/63953
Improving the Permalink Structure for ?attachment_id=123

---

#2270

Inline images and attachments

All inline images in an Article should also appear in attachments.
FEP-b2b8: Long-form Text
https://codeberg.org/fediverse/fep/src/branch/main/fep/b2b8/fep-b2b8.md#content

Any embedded media like images, video or audio in the content property should also be listed in the attachment property so that consumers can pre-fetch the media.

FEP-1311: Media Attachments introduces the concept of multiple media versions and licensing.
https://codeberg.org/fediverse/fep/src/branch/main/fep/1311/fep-1311.md#multiple-media-versions

FEP-e232: Object Links
https://codeberg.org/fediverse/fep/src/branch/main/fep/e232/fep-e232.md
This could be useful for inline images as object links.

Issue with WordPress:

• Single inline images are less common than galleries.
• The gallery block often includes multiple media versions in the content itself.
• A simple inline-image model is insufficient.
• A more flexible approach may resemble FEP-c16b (Formatting MFM functions).

---

Multiple media versions

For heavy photologs (up to 50 images per post), embedding all versions in the Article object is inefficient.

• Articles should reference an attachment container URI (e.g., improved attachment_id permalinks).
• The container provides access to all media versions.
• The attachment property should only include the representative URI + main URL.
• [UploadMedia endpoint](https://www.w3.org/TR/activitypub/#uploading-media) can be used to handle version arrays more efficiently.

Related core proposal:
https://core.trac.wordpress.org/ticket/63953
Improving the Permalink Structure for ?attachment_id=123

[Jiwoon-Kim]

https://docs.akkoma.dev/stable/development/ap_extensions/#uploadmedia

Deprecated and Removed Extensions

The following extensions were used in the past but have been dropped. Documentation is retained here as a reference and since old objects might still contains related fields.

Actor endpoints

The following endpoints used to be present:

• uploadMedia (https://www.w3.org/ns/activitystreams#uploadMedia)

uploadMedia

Inspired by https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload, it is part of the ActivityStreams namespace because it used to be part of the ActivityPub specification and got removed from it.

Content-Type: multipart/form-data

Parameters: - (required) file: The file being uploaded - (optional) description: A plain-text description of the media, for accessibility purposes.

Response: HTTP 201 Created with the object into the body, no Location header provided as it doesn't have an id

The object given in the response should then be inserted into an Object's attachment field.

---

As you know, Lemmy includes ActivityStreams Dislike activities, which are not part of the official ActivityPub specification. I believe that CMS platforms like WordPress or Ghost absolutely need an uploadMedia endpoint.

Exactly — the uploadMedia endpoint is one of those things that got deprecated from the formal ActivityPub spec, but in practice, many CMS implementations like WordPress or Ghost still need a way to receive and process media uploads.

Here’s why it matters:

---

🔹 Context

• ActivityPub vs ActivityStreams: ActivityPub defines actors, objects, and activities, but it doesn’t mandate media upload endpoints. Media handling is often left to implementations.
• uploadMedia: Historically, it allowed an actor to send a file (image, audio, video, document) via multipart/form-data and receive an object representing the media. That object could then be referenced in an attachment field of a Note, Article, or other object.
• Lemmy and similar: Lemmy has dislike activities that aren’t part of official ActivityPub, showing that practical implementations often diverge.

---

🔹 Why CMS need it

1. Direct media attachment: When creating posts with images or videos, users expect to attach media directly instead of just hotlinking.
2. Remote federation: Without an endpoint to handle uploads, federated instances can only reference remote media, which breaks workflow for inline attachments.
3. JSON-LD object creation: The uploaded media object can carry metadata like name, mediaType, url, duration, etc., enabling richer display and semantic interoperability.

---

🔹 Practical approach

For WordPress or Ghost:

1. Implement an uploadMedia endpoint on the actor (user) resource.
2. Accept file (required) and description (optional) as multipart/form-data.
3. Create a media object, store it locally, and return it in the response.
4. Allow posts (Note, Article) to reference this media object in their attachment field.
5. Optional: support remote caching, licensing metadata, and different media versions for performance.

---

In short: even if deprecated in spec, uploadMedia is essential for real-world CMS that want robust ActivityPub federation with media support.

If you want, I can draft a WordPress-style uploadMedia implementation plan that fits current FEP guidelines and the Media Library model. Do you want me to do that?