Craft

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

  • image is every file's main picture. A JSON file has it whatever its type's schema says. A Markdown file keeps it in the header, beside name and description, 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, overlayUrl and 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, a data: 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://…" }.
  • null keys are dropped.

How a picture shows

  • generation.status is generating: a spinner, whatever url says.
  • generation.status is error: the error, with generation.error.
  • A generating or error mark older than 10 minutes is treated as dead, and the picture slot shows empty.
  • Otherwise url, cropped around focalPoint, with overlayUrl on top. A picture with animation plays 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.