Image fields
Every picture on a file is an image object, not a bare link. The same object holds the file's main picture, any image field a type declares, and the picture of a project, a file type or a game.
{
"image": {
"url": "https://media.craftrpgs.com/…/aragorn.webp",
"focalPoint": { "x": 0.5, "y": 0.1 },
"generation": {
"status": "success",
"startedAt": "2026-11-02T10:14:03.000Z",
"finishedAt": "2026-11-02T10:14:21.000Z",
"prompt": "A weathered ranger in a green cloak, storm-grey eyes"
}
}
}
Where image fields are
imageis every file's main picture. A JSON file has it whatever its type's schema says. A Markdown file keeps it in the header, besidenameanddescription, as the same object written in YAML.- Image fields a type declares hold the same object. They are fields of the image type (field types), at any depth, in lists and in objects.
- No picture is the field left out, or
{}.
Rules every saved picture meets
- Every URL is on Craft's media host.
url,backgroundRemovedUrl,overlayUrland the video URLs must point at Craft's own storage, so a picture has to be generated or uploaded first. A link to another site, adata:URL or a chat attachment is refused. In image fields a type declares, a URL the file already stored is kept, wherever it moves, so older files stay editable. - Every key is optional. On
image, a key not listed below is refused. - A string is turned into an object.
"https://…"is stored as{ "url": "https://…" }. nullkeys are dropped.
How a picture shows
generation.statusisgenerating: a spinner, whateverurlsays.generation.statusiserror: the error, withgeneration.error.- A
generatingorerrormark older than 10 minutes is treated as dead, and the picture slot shows empty. - Otherwise
url, cropped aroundfocalPoint, withoverlayUrlon top. A picture withanimationplays its video instead, where it can.
Keys
url
The picture, on Craft's own media host. Missing while a generation runs and after one failed.
Type: string, optional.
A finished generation sets it, so leave it out of a generation request.
backgroundRemovedUrl
The same picture with its background removed (a cutout), which lets a character stand in the scene instead of sitting in a frame.
Type: string, optional.
focalPoint
The point kept in view when the picture is cropped to fit, from 0 to 1 across (x) and down (y).
| Key | Type | Required | What it is |
|---|---|---|---|
x |
number |
yes | Across, from 0 (left edge) to 1 (right edge). |
y |
number |
yes | Down, from 0 (top edge) to 1 (bottom edge). |
A picture generated for a character starts at { "x": 0.5, "y": 0.1 }, near the top,
to keep the face in view.
overlayUrl
A second picture drawn on top of this one, such as a logo.
Type: string, optional.
animation
Video versions of a picture that moves, played muted on a loop. url stays the still.
| Key | Type | Required | What it is |
|---|---|---|---|
kind |
"animated_gif" | "generated_video" |
yes | How the picture came to move: animated_gif for an uploaded animated GIF, PNG or WebP, converted to video; generated_video for a clip generated from a still. |
posterUrl |
string |
yes | The still shown before the video plays, and wherever it can't. |
mp4Url |
string |
yes | The video every browser can play. |
webmUrl |
string |
A smaller video for browsers that play WebM, when one was made. |
Uploading an animated GIF, PNG or WebP stores the moving picture this
way: url is its still, and the original GIF is not kept.
generation
How an AI generation of the picture went. Missing on uploads.
| Key | Type | Required | What it is |
|---|---|---|---|
status |
"generating" | "success" | "error" |
Where the generation stands: generating while it runs, success once the picture is in url, error when it failed. |
|
startedAt |
string |
When the generation started, as an ISO 8601 date and time. | |
finishedAt |
string |
When it finished or failed, as an ISO 8601 date and time. | |
prompt |
string |
The prompt the picture is generated from. | |
error |
string |
What went wrong, in words a person can read, when status is error. |
A file with a running generation shows a spinner on its picture in every view, and the GM can see that a picture is on its way.
variations
Named alternates of the picture, such as a character's expressions, each with its own picture and generation.
| Key | Type | Required | What it is |
|---|---|---|---|
name |
string |
yes | The state this variation shows, such as the expression happy. |
url |
string |
The variation's picture. | |
backgroundRemovedUrl |
string |
The variation's picture with its background removed (a cutout). | |
animation |
{ kind, posterUrl, mp4Url, webmUrl? } |
A looping video of the variation, generated from its still. | |
generation |
{ status?, startedAt?, finishedAt?, prompt?, error? } |
How the variation's own generation went. |
Limits: at most 16, one per name.
Each name matches an expression (or other state) of the file's type. Character expressions are the first use: expressions.