Chapter 07 · Writing articles
Hero images
How Serpio generates and checks the featured image for each article, what the statuses mean, what happens when it fails, and how each destination receives it.
Updated Sep 22, 2026 · 4 min read
On this page
As soon as a draft is saved, Serpio queues a background job to create its featured image. The workspace calls it the Featured image; publication labels call it the hero. Article cards show a Creating hero image placeholder until it lands, and nothing about the article waits on it except sending.
How the image is generated and checked
- 1
Build a prompt from the article
An interpreter reads the article, Brand Book and selected image style and creates a concrete visual scene. The renderer receives only that scene, not the article text. No-text prompt rules remain, but output is not automatically checked for text or style fidelity.
- 2
Choose the visual style
Open Image styles on the Articles page and enable one or more of the six visual approaches. New articles rotate through multiple selections in order. Brand Book palette, composition, visual direction, and things to avoid still guide every result, but the style preference itself lives with Articles.
- 3
Generate one image
Serpio requests exactly one high-quality image. It does not buy a batch of alternatives or generate extra candidates for comparison.
- 4
Review the result yourself
Automated OCR and visual QA are disabled. Review the image yourself for unwanted text, relevance, brand fidelity and visual style before publishing.
- 5
Validate and store
The raster image is validated for dimensions and file size, converted to an RGB WebP, and uploaded. The final prompt, selected style, model, provider, dimensions, content hash, and cost stay with the article for reproducibility. Invalid files and uncertain provider charges still stop the operation.
Statuses you will see
- pending
- Queued and not started. Cards and the workspace show the placeholder.
- generating
- A worker is on it. Publish is disabled with the hint to wait for the image.
- ready
- The image is in place and the alt text is filled in.
- failed
- Three attempts did not produce a passing image, or a provider error stopped it. The article proceeds without a hero.
- disabled
- Image generation is switched off for the deployment. Treated like failed for publishing.
Failed attempts retry with a delay, up to three in total. If a job is lost to a restart, a sweep every five minutes re-queues any article still pending or generating after two minutes, as long as it is less than a day old. You do not need to prod it.
What you can change
The Image styles control on the Articles page offers six permanent previews: Professional editorial, Cinematic, Paper cut, Soft 3D, Geometric editorial, and Ink and wash. You can enable any combination; at least one stays selected. The Featured image panel in the workspace shows the result and an Image alt text field. You can overwrite its automatic alt text, and the Publishing checklist ticks Featured image and Image alt text when both are present.
When it fails
A terminal failure does not block anything. Publish becomes available, the Export article dialog notes "No hero image is ready. The article content can still be exported.", and an automatically delivered scheduled article can proceed once the image reaches a final state. While the image is still generating, Publish is disabled so a delivery never has to wait on it; the Waiting for hero image label exists for the rare case where one does, and it moves on by itself.
How destinations receive it
| Destination | What happens to the hero |
|---|---|
| WordPress | Uploaded to the Media Library with the alt text and set as the post's featured image. A media upload problem becomes a warning on the delivery, not a failure. |
| Ghost | Set as the feature image with alt text, trimmed to Ghost's 125-character limit. |
| Blogger | Embedded as the first image in the post body with the alt text. |
| DEV / Forem | Set as the cover image by URL. |
| Webhook | Delivered inside the JSON payload as the hero URL and alt text for your receiver to handle. |
The Content package export bundles the image with the HTML, Markdown and JSON so you can carry it to a platform that is not connected. See field mapping and destinations.
Common questions
Why is there no text or logo in the image?
By design. Generated text is unreliable and generated logos can misrepresent real brands, so every visible surface must remain blank and unbranded.
Can I use my own photo instead?
You can upload a replacement in the workspace. It receives file validation only, without paid visual QA.
Does the image count against my credits?
No. Article credits count saved articles only.
Related guides
What the Brand Book is and how Serpio uses it
The Brand Book is a six-chapter system Serpio writes from your saved site analysis, then reuses on every article and hero image. What it holds, who can use it, and what it is not.
Read guideA tour of the article workspace
What each part of the article page does: the editor, the side panels, the status pill, autosave, and the Preview, Export and Publish actions.
Read guideDestinations and field mapping for native connections
Which connections ask you to choose a site or blog, what Serpio puts in each field at the destination, and when the field mapping controls appear.
Read guide