Images
Three ways in, mutually exclusive — and why an agent can't take your file.
Three inputs, exactly one per call
A featured image can come from three places. They are mutually exclusive: supplying more than one is rejected outright, never silently resolved. Pressbotics will not guess which one you meant.
| Parameter | What it is | How it behaves |
|---|---|---|
| featured_image_url | A publicly reachable URL | Pressbotics downloads it and sideloads it into the media library, then sets it as the featured image. |
| featured_image_id | An attachment already on the site | Reuse something in the media library. Find the id with list_media. |
| featured_media_ref | A file the person just uploaded | Produced by the media upload handoff: create_media_upload, the person uploads, get_media_upload returns the ref. |
An agent cannot accept your file
This surprises people, so it is worth stating plainly. When you paste a photo into a chat, the model sees an image — it cannot re-serialise those bytes into a tool argument. There is no path from "here is my photo" to a tool call carrying that photo. So the file has to reach us another way.
That way is the upload handoff: the agent calls create_media_upload, gives you a link, you upload the file on a signed-in Pressbotics page, and the agent polls get_media_upload until it can pass featured_media_ref. See Media uploads.
If an agent tells you it cannot use your image, this is why — and the handoff is the answer. It should never go hunting for a stock photo instead.
Reusing what is already there
If the image is already in the site's media library, do not upload it again. Call list_media, find the attachment, and pass featured_image_id. That avoids duplicate attachments cluttering the library.
Inline images are re-hosted
Every image in the markdown body — including :::cover heroes and :::gallery images — is downloaded and uploaded into the site's media library. Nothing hotlinks to an external host, so the post does not break when the source URL disappears. The response reports inline_images with total, failed and errors. An image that cannot be fetched is REMOVED from the post body and listed in errors; the post still publishes rather than being held back for one broken picture.
Captions
Markdown's title argument becomes a real WordPress figcaption. Without a title argument no caption is rendered. This is the only way to caption an image — alt text is not a caption.
What can go wrong
- image_status "failed" with an unreachable URL, an HTML error page returned instead of an image, or a file too large for the host to sideload.
- featured_image_id pointing at an attachment on a different site. Ids are per-site — always take them from list_media on the target site.
- Two image inputs on one call. Rejected. Send one.
- image_status "ok" but nothing visible on the post: the image did attach, and your theme is not displaying featured images on single posts.