HEADLESS RENDERER / V1

Pixels on demand.

One endpoint turns text and the same options as the studio into editable SVG, self-contained animated SVG, or production-ready PNG.

GET · POST/api/v1/render

Cacheable SVG URL

Use GET when parameters fit in a URL. Responses are deterministic, cached, and carry an ETag.

curl --get 'https://pxface.com/api/v1/render' \
  --data-urlencode 'text=HELLO
THERE' \
  --data 'format=svg' \
  --data 'ratio=fit' \
  --output hello-there.svg

PNG from JSON

Use POST for structured agent calls. PNG and SVG come from the exact same render scene.

curl 'https://pxface.com/api/v1/render' \
  --header 'Content-Type: application/json' \
  --data '{"format":"png","options":{"text":"HELLO\nTHERE","ratio":"square","effect":"wave","effectAmount":1.1,"seed":42,"pixelOverrides":{"l0-c0-r0-x0":{"color":"#FF4E1A","offsetY":-1}}}}' \
  --output hello-there.png

Animated SVG loop

Animation samples the same renderer at fixed phases. Every frame is deterministic, shares one viewBox, and stays made of editable pixel elements.

curl --get 'https://pxface.com/api/v1/render' \
  --data-urlencode 'text=PIXELS' \
  --data 'format=svg-animation' \
  --data 'effect=assemble' \
  --data 'duration=3' \
  --data 'frameRate=12' \
  --output pixels-loop.svg

Choose the right motion format

The API returns native animated SVG. Use the Studio to encode those exact frames as GIF, transparent WebM, or broadly compatible MP4. MP4 fills transparent canvases with the chosen background.

Parameter reference.

Every studio control is available through the API. GET accepts flat query parameters. POST keeps format and download at the root and puts all render parameters inside options.

Scroll each table horizontally to see every column.

OpenAPI 3.1

Request

Choose the response format and browser download behavior.

Parameter	Type or values	Default	Effect
`format`	`svg \| png \| svg-animation`	`svg`	Selects a static SVG, PNG, or self-contained animated SVG response.
`download`	`boolean`	`false`	Returns the asset as an attachment instead of displaying it inline.
`duration`	`number 1-10`	`3`	Loop duration in seconds when format is svg-animation.
`frameRate`	`integer 4-30`	`12`	Fixed frames per second when format is svg-animation.

Content and color

Set the characters and the colors used to draw them.

Parameter	Type or values	Default	Effect
`text`	`string`	`HELLO\nTHERE`	Text to render. Supports 95 printable ASCII characters, up to 160 characters and 8 lines.
`foreground`	`#RRGGBB[AA]`	`#F1F0E9`	Pixel color in solid mode. The optional alpha pair controls opacity.
`background`	`#RRGGBB[AA]`	`#181816`	Canvas color. Also seeds the color family used by random mode.
`depthColor`	`#RRGGBB[AA]`	`#FF4E1A`	Color of the offset layers created when depth is greater than zero.
`colorMode`	`solid \| random`	`solid`	Uses one foreground color or a deterministic color for every pixel.
`seed`	`integer 0-4294967295`	`1347962433`	Controls the deterministic sequence used by random color mode.

Pixel remix

Transform each 3x5 cell independently with a deterministic effect.

Parameter	Type or values	Default	Effect
`effect`	`none \| spectrum \| explode \| wave \| glitch \| weave \| assemble \| relay \| scan`	`none`	Applies a deterministic grid-native transformation to individual pixels.
`effectAmount`	`number 0-2`	`1`	Controls the strength of the selected pixel effect without changing its identity.
`animationProgress`	`number 0-1`	`0.5`	Samples one deterministic point in the seamless loop. Values 0 and 1 resolve to the same frame.
`pixelOverrides`	`object (POST JSON)`	`{}`	Overrides color, offsets, opacity, scale, or rotation by stable pixel ID after the effect.

Spacing and form

Control the 3x5 grid, line layout, pixel geometry, and depth.

Parameter	Type or values	Default	Effect
`letterSpacing`	`number 0-8`	`1`	Horizontal design units added after every character.
`wordSpacing`	`number 0-16`	`3`	Width of a space character in design units.
`lineSpacing`	`number 0-12`	`2`	Vertical design units inserted between 5-pixel-high lines.
`pixelGap`	`number 0-0.8`	`0`	Inset inside every pixel. Zero keeps adjacent square pixels seamless.
`depth`	`integer 0-12`	`0`	Number of one-unit diagonal layers rendered behind the text.
`align`	`left \| center \| right`	`left`	Aligns each line within the width of the longest line.
`shape`	`square \| soft \| dot`	`square`	Renders each pixel as a square, a rounded square, or a circle.
`slant`	`boolean`	`false`	Offsets pixel rows to create an italic form.

Canvas and output

Size and frame the final SVG or PNG.

Parameter	Type or values	Default	Effect
`padding`	`number 0-200`	`20`	Padding on every side, as a percentage of the shortest content edge.
`ratio`	`fit \| square`	`fit`	Fits the canvas to the content or expands it to a centered square.
`transparent`	`boolean`	`false`	Removes the canvas rectangle from the exported asset.
`scale`	`number 1-256`	`48`	Output pixels per design unit. Changes dimensions, not the composition.

Agent resources.

Three plain files make the renderer easy to discover and use. Open them directly, copy their URLs, or give them to an agent.

llms.txt

A compact index of PXFACE, its endpoint, limits, license, and canonical documentation.

text/plainSKILL.md

Ready-to-use instructions for agents that need to generate, validate, and save an asset.

text/markdownopenapi.yaml

The complete OpenAPI 3.1 contract for clients, tool calling, validation, and code generation.

text/yaml

Built for automation.

Errors include field-level issues. Output dimensions, renderer version, loop duration, and frame rate are exposed as headers. Public CORS is enabled; the current limit is 60 requests per minute per IP. GET responses include an ETag for cache validation. Building a JavaScript frontend? Use the local package to sample frames or render loops without a network request.