CardRenderRequestData

CardRenderRequestData is the JSON structure encoded in the {hash} path segment of the GET /render/card endpoint. It is also the element type of the cards array in FanRenderRequestData, used by the fan and album endpoints.

Fields

uint32

required

Character ID. Maps to the character image asset on disk. See the asset path logic section below for how id and variant are combined into a file path.

variant

uint8

required

Selects which variant image to use for the character.

Value	Meaning	Asset path
`0`	Base image	`{cdn}/{id}.png`
`1`–`9`	Numbered variant	`{cdn}/{id}/u{variant}.png`
`10`+	Extended variant	`{cdn}/{id}/x{variant}.png`

See Asset path logic for the full resolved paths.

dye

uint32

required

24-bit RGB color integer applied to the color layer of the frame. Valid range: 0x000000–0xFFFFFF (0–16777215).

The dye field is ignored by the SnowglowFrame (frame_type: 2), which has a static layer only and no color layer.

kindled

boolean

required

When true, enables the kindled (enhanced) frame variant. Frames that do not support kindled rendering silently ignore this field.

Frame type	Supports kindled
`0` MoonweaverFrame	Yes
`1` EssentiaFrame	No (silently ignored)
`2` SnowglowFrame	Yes

frame_type

uint8

required

Selects the card frame to render.

Value	Name	Dimensions	Layers	Kindled	Dye
`0`	MoonweaverFrame	550×800	Static + color	Yes	Yes
`1`	EssentiaFrame	550×800	Color only	No	Yes
`2`	SnowglowFrame	550×800	Static only	Yes	No

offset_x

int32

Horizontal offset in pixels. Accepted and parsed, but not currently used in the render pipeline. Reserved for future use.

offset_y

int32

Vertical offset in pixels. Accepted and parsed, but not currently used in the render pipeline. Reserved for future use.

save_name

string

If provided, the rendered card is saved to ../asset/public/render/{save_name}. On subsequent requests with the same save_name, the image is served directly from disk without re-rendering.

When used inside the cards array of a fan or album request, save_name caches the individual card render, not the composite output. To cache the composite, set save_name on the top-level FanRenderRequestData object.

Asset path logic

The character image path is resolved as follows:

let image_path = if data.variant == 0 {
    format!("{}/{}.png", CDN_CHARACTER_IMAGES_PATH, data.id)
} else {
    format!(
        "{}/{}/{}{}.png",
        CDN_CHARACTER_IMAGES_PATH,
        data.id,
        if data.variant < 10 { 'u' } else { 'x' },
        data.variant
    )
};

Resolved examples (where CDN_CHARACTER_IMAGES_PATH = ../asset/private/idol):

`id`	`variant`	Resolved path
`1`	`0`	`../asset/private/idol/1.png`
`1`	`3`	`../asset/private/idol/1/u3.png`
`1`	`10`	`../asset/private/idol/1/x10.png`
`42`	`0`	`../asset/private/idol/42.png`

Example

{
  "id": 1,
  "variant": 0,
  "dye": 7864319,
  "kindled": false,
  "frame_type": 0,
  "offset_x": null,
  "offset_y": null,
  "save_name": "card-1-base.png"
}

offset_x and offset_y may be omitted entirely or set to null. They are parsed by the server but do not affect the rendered output in the current version.

Endpoints

Data Models

Fields

Asset path logic

Example

Build docs developers (and LLMs) love

Endpoints

Data Models

​Fields

​Asset path logic

​Example

Build docs developers (and LLMs) love

Fields

Asset path logic

Example