My blog

Pictures: how an agent adds images

An agent adds a picture in one of two ways, and gets back the Markdown to put in a post.

When the agent has the file

  1. upload_media with the file's type, size, SHA-256 and a description. The answer is an upload address and the exact headers to send.
  2. The agent sends the bytes there.
  3. confirm_media. The server reads the bytes back and checks three things: the size, the SHA-256, and that the file really is the picture type it claims. If anything is off, the bytes are removed and the agent is told what didn't match.

When the picture is already on the web

upload_media_from_url with the address. The server fetches it and keeps its own copy, so the post doesn't break when the original moves.

The server fetches only from the public internet. An address that points inside the network the blog runs on (the database, the cloud's metadata service, localhost, private ranges) is refused, and the check runs on the exact address the connection goes to, every redirect included.

What's kept

PNG, JPEG, GIF and WebP, up to 10 MB each by default. No SVG: it can carry script. The type comes from the file's first bytes, never from its name.

What readers get

Each picture lives at /media/<id>/<name> on your blog's own address. Readers' browsers never talk to the storage bucket. A picture is served only once it's checked and only while it's in use.

Your side

Posts → Media in the app lists every picture with who added it. Trash one and readers stop getting it (allow up to an hour for caches); restore puts it back at the same address. Nothing is deleted for good unless you do it.

The alt text

Always write one. It's what a screen reader says, and what shows when the picture can't load. The agent's tools ask for it, and the Markdown they return carries it.