render_text

Render exact text into a PNG in a chosen font, such as an uploaded brand font.

A deterministic file operation: no model runs and no Creative Units are spent. Use it for
text that must read exactly or be set in a given typeface: image models misspell text and
cannot use a font file. It sets flat, single-colour type, so lettering that must look drawn
into the art is a generation instead. The font is a workspace font file (`font_file_id`) or
else a named `font_family`. The text wraps at the canvas width and sits on the canvas by
its alignments; text that does not fit is refused with the size it needs. The background is
transparent unless `background_color` is set. Size the canvas to roughly the box the text
will fill in the final image, so it is barely scaled there. To letter an image, pass the
returned `file_id` to `compose_image` as a layer above the base image, placed with
`anchors` and sized with `fit_and_pad`.
The image is saved to the workspace library and, when the call runs in a session, placed on
its board (`image.placed_on_board`).

Parameters

Parameter	Type	Default	Description
textrequired	string1–2000 chars	—	The exact text to render. A newline starts a new line and a long line wraps at spaces; text that does not fit the canvas is refused with the size it needs.
widthrequired	integer1–4096	—	Canvas width in pixels.
heightrequired	integer1–4096	—	Canvas height in pixels.
font_file_id	string (uuid)	—	Workspace file id of a font file (.ttf/.otf) already in the workspace library. Takes precedence over `font_family`.
font_family	string0–255 chars	Arial	Font family used when `font_file_id` is omitted: a standard font or a Google Fonts family name.
font_size	integer6–1000	64	Font size in pixels.
font_weight	integer100–900	400	100 to 900 in steps of 100: 400 regular, 700 bold. With `font_file_id`, pass the weight of the face you want from that file; 400 picks its regular face.
italic	boolean	false	Render the italic face.
color	string	#000000	Text color as `#RRGGBB` or `#RRGGBBAA`.
background_color	string	—	Canvas fill as `#RRGGBB` or `#RRGGBBAA`. Omit for a fully transparent canvas.
horizontal_alignment	enum	center	Where the text block sits on the canvas horizontally. One of: left, center, right
vertical_alignment	enum	center	Where the text block sits on the canvas vertically. One of: top, center, bottom
text_align	enum	center	How the lines of a multi-line block align with each other. One of: left, center, right
line_height	integer0–2000	—	Line spacing in pixels, for looser lines: a value at or below the font's natural line height gives its tightest spacing. Omit for the font's default spacing.
underline	boolean	false	Underline each line.
strikethrough	boolean	false	Strike through each line.
name	string0–120 chars	—	File name for the image.
workspace_idrequired	string (uuid)	—	The user's workspace id.
session_id	string (uuid)	—	Session whose board receives the image. Omit to only save it to the library.
project_id	string (uuid)	—	Optional project to add the result to; use list_projects to find project ids.