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. 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. 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. 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. 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. 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

DestinationWhat happens to the hero
WordPressUploaded 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.
GhostSet as the feature image with alt text, trimmed to Ghost's 125-character limit.
BloggerEmbedded as the first image in the post body with the alt text.
DEV / ForemSet as the cover image by URL.
WebhookDelivered 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.

Your next article starts here.

Turn a topic that is trending right now into your first article.

Write my first article

3 free articles a month. No credit card.

Allow Google Analytics cookies to help us understand which pages bring visitors and signups? This choice controls Google Analytics. Privacy policy