# 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.                                                                                |