Fonts
View as MarkdownEvery font a text layer uses must be available when you render. Pick a font from Blitframe's font library, or add your own font file to the project.
Use a library font
Search the font library, which Blitframe provides to every workspace:
GET /v1/fonts?q=mont&limit=20
{
"items": [
{
"family": "Montserrat",
"style": "Bold",
"slug": "montserrat-bold",
"declaration": { "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" },
"license": "ofl",
"previewUrl": "https://…/montserrat-bold.png"
}
],
"next": null
}
Copy the font's declaration into fonts.list in data.json, and use its fName as the text document's f. Agents search with the list_fonts MCP tool.
| Parameter | Description |
|---|---|
q |
Part of the family, style or slug, any case. |
limit |
1 to 1,000, default 100. |
after |
The next value of the previous page, while it is not null. |
Fonts are listed by slug. GET /v1/fonts/{slug} returns one font.
| Field | Meaning |
|---|---|
previewUrl |
A PNG of the font's name set in the font, valid for an hour, or null when the font has no preview. |
license |
ofl (SIL Open Font License), apache or ufl (Ubuntu Font Licence) when it is recorded, otherwise null. |
Add your own font
For any other typeface, add the font file to the project as fonts/Family-Style.ttf. Name it after the family and style it has in fonts.list (how fonts are matched). This edit adds one and confirms you are licensed to render with it:
{
"fontLicenseAccepted": true,
"files": [{ "path": "fonts/Inter-Bold.ttf", "contentBase64": "AAEAAA…" }]
}
Fonts can be TTF, OTF, WOFF or WOFF2, up to 64 MB each. Text fitting measures only TTF and OTF files.
Each font is checked and prepared for rendering when it comes in: inline in an edit, when you complete its upload, or in an imported ZIP. A file that isn't a valid font is rejected.
How fonts are matched
Blitframe looks for each font in two places, in this order:
- Project fonts: font files in the version.
- The font library.
In data.json, each entry in fonts.list has a family and a style:
{ "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" }
Blitframe builds a lookup name from them: lower case, no spaces, joined with a hyphen. For the entry above that is montserrat-bold.
| Source | Matches by |
|---|---|
| Project fonts | File name, lower-cased and with spaces removed. Add the font above as fonts/Montserrat-Bold.ttf. Any folder works. |
| Library fonts | Their slug. |
Only fonts that a text layer uses need to be available. A project font with the same lookup name as a library font takes priority.
Licensing
Only upload fonts you are licensed to use for rendering video. Project fonts are used only for your own renders.
A request that adds a font file (.ttf, .otf, .woff or .woff2) to a version must confirm it with "fontLicenseAccepted": true. That applies to:
- edits that add a font file,
- creating a project from a ZIP, or importing a ZIP into a project, when the ZIP contains a font file.
Without it, the request fails with 400 font_license_required and nothing changes. A large ZIP import that answered 202 reports it in its error.
You don't need it for:
- other files,
- replacements that use a library font or a font already in the version,
- a font copied from another version of your workspace with
fromVersionId, - duplicating a project, since the license was confirmed when the font first came in,
- renders, since a render's replacements can't add a font file.
File capabilities mark the font types with fontLicenseRequired: true.
When a font is missing
The version's problems name the missing font and the file name to add, for example:
Font 'Montserrat-Bold' (Montserrat Bold) is not in the project or the font library. Upload it as fonts/Montserrat-Bold.ttf.