Images and files
With the media abilities exposed, an assistant can fill in the pictures as well as the words: "add these twelve Books with their covers", "use the photo I just gave you as this Writer's portrait", or "write alt text for every image that has none".
The assistant adds a file to the media library, gets back its id, and then uses it like any other value: as a post's featured image, or in an Image, Gallery, Files, Video or Audio field.
Three ways a file reaches your site
- From a web address. You give the assistant a link to an image (or it finds one, or an image generator gives it one). Your site downloads the file itself.
- From the assistant's side. A photo you attached in the chat, a file on your computer, an image the assistant generated. The assistant asks your site for a one-time upload link, and sends the file to it with its own tools.
- Written as text. The assistant writes simple files itself: an SVG icon or a placeholder graphic, a CSV. Nothing is downloaded.
An assistant can't paste a photo into a request. It sees an image as a picture, not as the file's bytes. That's why files from your side go through an upload link.
What your assistant can use
| Your assistant | From a web address | From its side |
|---|---|---|
| Coding assistants with a terminal (Claude Code, Cursor, Codex, VS Code, Windsurf) | Yes | Yes. It runs the upload command for you |
| Chat apps without a terminal | Yes | Only if it can run code that reaches your site. Otherwise, give it a link instead |
An upload link works once, for one file, and only for 15 minutes. It adds a file as you, and can't read, change or delete anything.
What to know before exposing them
- A file is public as soon as it's added. Anyone with its address can open it, like any file in the media library. Only images are accepted unless the assistant asks for videos, audio or other files.
- Your site only downloads from the public internet. Addresses on your own network or the server itself are refused, and so is any redirect that leads to one. A link that hides what it points at can't make your server fetch something private.
- Your upload limits still apply. The largest file is your site's usual upload limit. On a network, a site that's out of storage space can't take more. Only file types WordPress accepts are allowed, and the file's content has to match its name.
- The same file isn't added twice. If the library already has a file with exactly the same contents, the assistant gets that one back instead of a copy, with its title and alt text left as they were.
- Ask for alt text. The assistant can set it when it adds an image, or afterwards. Images without alt text are easy for it to find.
- Deleting a file is permanent. WordPress has no trash for media, so the file and all its sizes are gone. A post that used it as its featured image loses it; a field that held it keeps a reference to nothing. A careful assistant checks where a file is used before deleting it.
Related
Technical details for LLMs
- Abilities:
vx-framework/import-media(urlorcontent+filename;items≤ 20),vx-framework/create-media-upload(one link;items≤ 20 links),vx-framework/update-media(title, alt, caption, description,attach_to; patch;if_match),vx-framework/delete-media(id/ids; permanent; destructive),vx-framework/query-media(read:search,kind,mime_type,attached_to,missing_alt,ids,limit/offset). All writes in the Media domain, off on MCP until exposed. - Assigning:
vx-framework/update-postfeatured_image: <id>; media and gallery fields take attachment ids throughvx-framework/set-post-values(fields validate type and size on write). - Common details:
filename,title,alt(images only),caption,description,attach_to(post id, the library parent; displays nothing).accept:image(default),video,audio,file,any.reuse_existing(default true): a matching SHA-256 returnsreused: trueand leaves details unchanged. - Upload link: a
create-media-uploaddry run returnsuploadwithurl,method,max_bytes,accept,filenameandexpires_in(900), and no token; a real call addsheaders,expires_atandcommand.POSTorPUT https://example.com/wp-json/vx-framework/v1/media/uploads, raw bytes as the body, headersX-VXFramework-Upload-TokenandContent-Type: application/octet-stream. No other authentication. Response 201 (200 when reused):attachment,undo. 401 = expired, spent, or missing token. A refusal the sender can fix (empty body, too large, wrong kind or content) keeps the link for up to 3 attempts in total; the error carriesattempts_left. - Downloads: http/https on ports 80, 443 or 8080; no credentials in the URL; every resolved IPv4 and IPv6 address must be public (link-local, CGNAT, private, loopback, documentation, multicast and IPv4-in-IPv6 forms refused); each redirect (≤ 5) re-checked; the URL must be printable ASCII and the host a plain name (no trailing dot, percent-encoding or non-ASCII; an international name in its
xn--form); the connection is pinned to the checked address with PHP's curl extension (required), refused when the pin didn't apply, and refused when curl connected to another address or port (vxframework_media_address_changed). Through a proxy WordPress is configured to use (WP_PROXY_HOST), the proxy resolves the host itself and its own rules decide what it reaches. 30 s per request. Hosts allowed throughhttp_request_host_is_external(core allows the site's own host and network sites) may use only the scheme's default port. A batch that runs out of time reports the files it didn't reach asvxframework_media_not_attempted. content: text only, ≤ 1 MB, extension decides the type (.svg,.csv,.txt). SVGs are sanitized as they're stored.- Pipeline:
media_handle_sideload(), sowp_handle_sideload_prefilter,get_allowed_mime_types(),wp_check_filetype_and_ext()and image size generation all run. Attachment meta:_vxframework_sha256,_source_url(downloads). - Undo: an import or upload →
vx-framework/delete-media;update-media→ itself with the previous values;delete-mediaand a link → none.