Skip to main content
GET /render/fan/{hash} Renders a set of cards fanned out in a circular arc and returns raw PNG bytes. The {hash} path segment encodes a FanRenderRequestData JSON object.

​
Path parameter

​
hash
string
required
Base64 standard alphabet, no-padding encoding of a FanRenderRequestData JSON object. The struct contains an array of cards and an optional top-level save_name. See Hash encoding.

​
Fan layout

Cards are rendered in parallel and then composited into a single image:
  • Each card is rotated by 5.0° × its position index around a circle whose centre is 3,000 pixels below the bottom edge of the card stack.
  • Stacking order: the centre card is drawn on top of all others; outer cards are drawn underneath their inner neighbours. In a 5-card fan, the draw order from bottom to top is: outermost-left, outermost-right, next-left, next-right, centre.
  • Output dimensions are calculated dynamically to contain all rotated cards without clipping.
Because the output size depends on the number and rotation of cards, there is no fixed output resolution for the fan endpoint.

​
Examples

# Three cards with different frame types
HASH=$(echo -n '{
  "cards": [
    {"id":1,"variant":0,"dye":7864319,"kindled":false,"frame_type":0},
    {"id":2,"variant":1,"dye":255,"kindled":true,"frame_type":1},
    {"id":3,"variant":0,"dye":65280,"kindled":false,"frame_type":2}
  ]
}' | tr -d '\n' | base64 -w0 | tr -d '=')

curl -o fan.png "http://localhost:8899/render/fan/$HASH"

​
Response

200 OK — Raw PNG bytes.
HeaderValue
Content-Typeimage/png
X-Sourcerendered on request or loaded from disk cache
X-Processing-Timee.g. 48.210ms

​
Errors

StatusBodyCause
400bad request - provided card hash is invalid{hash} failed base64 decoding
400bad request - provided card hash is a valid json but does not follow API structureJSON decoded but does not match FanRenderRequestData
500failed request - invalid frame type providedA card’s frame_type is not 0, 1, or 2
500failed request - missing main image asset.A character image file was not found
500failed request - failed to decode main image asset.A character image file could not be decoded
500server error - failed to copy characterError compositing a character layer
500server error - missing required asset: {key}A frame asset file is missing
500server error - cannot write card image to bufferPNG encoding failed
500gateway timeout - asset render took more than 5 secondsRender exceeded the 5-second timeout

Build docs developers (and LLMs) love

Get started for freeTalk to us