When a person places an image, they glance at it and know in a second whether it fits the section, reads cleanly behind text, and matches the brand. A program never sees the picture that way. It sees a response object: a set of named fields. Everything your builder decides — which image to pick, where to put it, how to label it, whether it's safe to publish — comes from those fields and nothing else.
So the practical question isn't "is metadata important." It's: which fields let an automated builder make a defensible decision, and what does each one let you decide? This walks an illustrative internal record one field at a time, grouped by selecting, labeling, placing, and rights-checking.
This builds on the broader workflow in how to add website images automatically with an image API. It is vendor-neutral design guidance, not documentation for a live Picdrome API.
The fields a program actually reads
Here is an illustrative record based on metadata used by Picdrome's content, grouped by what each field is for. Normalize the actual source fields into your own versioned contract; do not assume these names are a service response.
| Field | Group | What an automated builder uses it for |
|---|---|---|
category | Selection | Coarse filter: which kind of image this is |
tags | Selection | Fine matching on subject, style, and use-case facets |
faq_what_is_this_image | Selection | Confirm the subject, setting, and mood before placing |
faq_when_to_use_this_image | Selection / placement | The page sections this image is meant for |
faq_who_this_image_is_for | Selection | The business types and audiences it suits |
alt_text | Labeling | The accessible description to carry onto the page |
image_file | Placement | The image asset to render |
image_width / image_height | Placement | Dimensions and the aspect ratio you derive from them |
license | Trust | The usage terms, linking to Picdrome Image License |
generation_model | Trust | The AI-generation signal for honest disclosure |
name, slug | Reference | Stable identity for linking and caching |
created_at, updated_at | Reference | Freshness and cache invalidation |
A note on terminology before we go field by field. The fields you'll lean on most for placement are image_file, image_width, and image_height. A single dedicated aspect-ratio field and a separate small thumbnail_url rendition are not part of the documented schema, so derive what you need from the fields that exist. Don't code against a field name you wish were there.
Selection: how the program chooses the right image
Selection is the part that goes most wrong when no human is looking. A wrong-but-plausible image — a warehouse photo on a yoga studio's homepage — passes silently because the URL resolved and the dimensions fit. The selection fields exist to stop exactly that.
category — the coarse filter
category tells you the broad bucket an image belongs to. Use it as your first narrowing pass, not your final answer. It's reliable for "is this even in the right neighborhood," but on its own it's too blunt to place an image with confidence. Filter on category, then rank within it using the more specific fields below.
tags — the fine match
tags is where the real matching happens. Picdrome's tags carry the facets the rest of a generic stock API usually hides: the page section an image suits, the business type it's built for, and the visual style. That structure is what lets a program reason about fit instead of guessing from a filename. If you're driving selection mainly from these facets, the mechanics are covered in search images by business type and page section via API.
The what / when / who context fields
These three FAQ fields are written per image and describe that specific frame, not its category:
faq_what_is_this_image— the subject, setting, composition, and mood. Use it as a sanity check: does the described scene actually match the section you're filling? A program can compare this text against the page's purpose before committing.faq_when_to_use_this_image— the concrete placements it's meant for, like a homepage hero, a service page, an about section, or a blog header. This is the single most useful field for section-level placement, because it states intent directly instead of making you infer it from dimensions.faq_who_this_image_is_for— the business types and audiences it serves. Match this against the site's detected industry to avoid the warehouse-on-a-yoga-page problem.
Treat these as the human judgment, pre-written. They're the closest thing your program has to a person saying "yes, this one fits here."
Labeling: alt text you should carry, not rewrite
alt_text is Picdrome's accessible description of the actual pixels — what the image shows, written to be read by a screen reader. The strong default for an automated builder is simple: carry the provided alt_text straight through to the page.
Two failure modes to avoid:
- Dropping it. Shipping an image with an empty
altattribute (when the image is meaningful, not decorative) leaves screen-reader users with nothing. The field is right there in the response; use it. - Auto-rewriting it carelessly. Regenerating alt text from a keyword or the page's target phrase usually makes it worse — it stops describing the image and starts describing what you want to rank for. The provided
alt_textalready describes the real frame, which is the point of alt text.
There's a narrow exception: if an image is purely decorative in its on-page context (a background texture behind a heading, say), an empty alt="" is the correct accessible choice. That's a context decision your placement logic makes, not a reason to discard the field globally. See the developer hub for the maintained record design. This is general accessibility guidance, not professional advice; if you have specific compliance requirements, confirm them with someone qualified.
Placement: dimensions, ratio, and the asset URL
Placement is the mechanical part, and the relevant fields are image_file, image_width, and image_height.
image_fileis the asset you render — the URL or path your<img>(or builder block) points at.image_widthandimage_heightgive you the native pixel dimensions. From those two you derive the aspect ratio yourself (width / height), which is what you actually match against a slot: a 16:9 hero band, a roughly square card, a tall sidebar.
Why derive rather than wait for a field? Because a wrong ratio is a visible defect — a portrait image jammed into a wide hero either letterboxes or crops the subject's head off, with no human there to catch it. Checking the derived ratio against the target slot before you place is cheap insurance.
Set explicit width and height (or a CSS aspect-ratio) on the rendered element so the browser reserves space and the layout doesn't jump while the image loads. A correctly sized image that loads without shifting the page is most of what "fits the section" means in practice.
On renditions: the documented schema does not include a distinct small-thumbnail URL alongside the full asset. Point at image_file and let your own pipeline or builder handle resizing and responsive variants rather than coding against a thumbnail_url field that is not documented.
Trust: license and AI-generation disclosure
These two fields decide whether it's safe to publish. Skip them and you can ship a technically-placed image that's mislabeled or non-compliant.
license — and it travels with the image
The license field should link to the current source terms. For Picdrome images, use Picdrome Image License, do not infer an attribution rule, and block publishing when the intended use is not clearly authorized.
The practical rule for a pipeline: keep the license value attached to the image as it moves downstream, through caches and into whatever you render. License that gets stripped at the first hop can't be honored later, and a generated site that can't say where its images come from is one you can't audit. This is general information, not legal advice; the full terms live at Picdrome Image License.
generation_model — the AI-generation signal
generation_model records that the image is AI-generated and which model produced it. Picdrome images are AI-generated, and your output should be honest about that where it's relevant.
The hard rule your program must encode: an AI-generated person is never a real customer, team member, or endorser, and must never be labeled as one. Don't let an automated builder caption a generated face as a named team member, drop it into a testimonial, or imply a real person uses or endorses anything. The documented schema uses generation_model as the disclosure signal rather than a separate flag; read the AI image disclosure page for how Picdrome frames this.
A field-priority checklist for automated placement
When you process a response with no human in the loop, run the fields in roughly this order. Each step can reject an image before you waste effort on the next.
| Priority | Field(s) | The decision it gates |
|---|---|---|
| 1 | license | Is this safe to use at all under the terms? |
| 2 | generation_model | Disclose AI generation; never label a generated person as real |
| 3 | faq_when_to_use_this_image, tags | Does it belong in this section? |
| 4 | faq_who_this_image_is_for, category | Does it fit this business type and audience? |
| 5 | image_width / image_height | Does the derived ratio fit the slot without bad cropping? |
| 6 | alt_text | Carry it through for an accessible, honestly labeled image |
| 7 | image_file | Render the asset, with explicit dimensions |
Trust fields first, because a beautifully-placed non-compliant image is still a problem you have to pull down. Fit next, placement after, labeling last — but never skipped.
For the full machine-readable picture of how a generator maps page sections to images, see how AI website builders pull in ready-to-use images, which covers the same fields from the builder's side.
In Plain English
This is a field-by-field guide to a vendor-neutral internal image record. Use category, tags, and use-case fields for selection; dimensions for placement; alt_text for accessible labeling; and source, current license, and AI-generated provenance to gate publishing. Do not code against undocumented source fields, and do not publish when the intended use or attribution rule is unknown. Start from the maintained Picdrome integration design guide.