Hero images

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

   The title, the summary, the named companies or products in the topic, and any source context attached to the idea become a fixed prompt for a 16:9 editorial illustration. The prompt forbids text, numbers, fake interfaces, charts and invented logos. Entity names are context only and are never spelled in the image.

2. 2

   Apply Brand Book guidance

   If the article was written with a Brand Book, its machine guidance for images is snapshotted onto the article: style tokens, a palette of hex colours, composition notes and things to avoid. The first palette colour leads the environment; the rest are accents. See Brand Book overview.

3. 3

   Generate candidates

   Two candidates by default, each with a different composition direction. If neither passes review and fewer than three exist, a third is made.

4. 4

   Review each candidate

   A strict art-director model scores four things: topical relevance out of 35, absence of forbidden elements out of 25, palette fidelity out of 20 and readability at card size out of 20. A candidate passes only if its total meets the minimum (72 by default), forbidden elements score at least 20 and relevance at least 22.

5. 5

   Keep the best

   The highest passing candidate is uploaded and the article gets its URL. Alt text is written from the reviewer's literal description, trimmed to 125 characters. If no candidate passes, the attempt fails.

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 Featured image panel in the workspace shows the image and an Image alt text field. Serpio fills the alt text automatically once the image is ready, and you can overwrite it; it saves with the rest of the draft and creates a new revision like any edit. 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

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.