Custom fonts and advanced text options

This page covers custom fonts, Google Fonts, predefined text templates, and text layer flags for videos. For styling parameters, color, multi-line text, and special characters, see Text layer options. For the layer syntax itself, see Layer syntax.

Custom fonts

By default, only universally available fonts are supported for text overlays. However, if you want to use a non-standard font, you can upload it to Cloudinary as a raw, authenticated file and then specify the font's full public_id (including extension) as the font for your overlay:

Custom font guidelines

• .ttf, .otf and .woff2 font types are supported.

• Custom fonts must be uploaded as raw, authenticated files.

  Tip

  You can upload custom fonts via the Media Library by creating (or using an existing) signed upload preset where the Delivery type option in the preset is set as Authenticated. You can use this upload preset when uploading files to the Media Library by configuring it as the default Media library upload preset for Raw files.

  Alternatively, you can select the signed upload preset you create for custom fonts in the Media Library upload widget's Advanced settings while uploading assets, if that option is enabled for your account.

• If your custom font's public ID includes slashes, specify the public ID path using colons as separators. For example: path1:path2:myfont.ttf.

• Make sure to include the file extension when referencing the public_id of the raw file. The extension must be specified in lower-case letters.

• To make use of bold or italic font styles, upload separate font files for each emphasis style and specify the relevant file in the overlay transformation.

• A custom font is available only to the specific product environment where it was uploaded.

• Underscores are not supported in custom font names. When uploading the font as a raw file, make sure the public_id does not include an underscore.

• As with any asset you upload to Cloudinary, it is your responsibility to make sure you have the necessary license and redistribution rights for any custom fonts you use.

Google Fonts

You can use any font available in the Google Fonts library by appending @google to the font name in your text overlay:

l_text:<font name>@google_<size>:<text string>

For example, to overlay "Enjoy luxury" in white using the Gravitas One Google Font at size 80:

co_white,l_text:Gravitas%20One@google_80:Enjoy%20luxury

All other text overlay styling parameters are supported in combination with Google Fonts, including decoration, alignment, letter spacing, and line spacing.

Google Fonts guidelines

• Font names are case-sensitive and must match exactly as listed on Google Fonts.
• When using the @google syntax, font weight must be specified as a numeric value (e.g. 400, 700) rather than a keyword such as bold or light. The numeric weight must be supported by the chosen font.
• To specify font size and font weight together, include the weight after the size, separated by an underscore. For example, to use Roboto at size 90 with a weight of 600:
  l_text:Roboto@google_90_600:Hello%20World

Predefined text templates

Instead of specifying the styling parameters every time you need to dynamically add a text overlay to an asset, you can use the public ID of a text image created with the text method of the upload API. The same styles that were used to create the text image will also be dynamically applied to the text overlay. The default text string of the text image is also used unless you provide a new text string, which can be useful if you don't want the text string to appear in the URL, or if the text string is very long.

For example, you can create a text image of "Sample text string" in 82 point, red, Roboto bold font, and the public ID of sample_text_style as follows:

This is the resulting text image:

You can then use the sample_text_style style in your text overlay, as follows: