☰

Documentation

Introduction

The Handwriting.io API turns text into images of handwriting. Getting started involves just four simple steps:

  1. for an account. It's free!
  2. Generate an access token.
  3. Call the API to list handwritings. Select one of these to use in the next step.
  4. Call the API to produce a PNG or PDF image.

Not ready to write code? You can try out everything without writing a single line of code by heading over to our Live Demo. You'll even be shown example code to produce any image you want.

Top

Access Tokens

To use the API, you will need an access token pair. for an account and generate a token pair from your dashboard to get started.

Your token pair (key and secret) should be included in all requests as the “username” and “password”, passed using HTTP basic access authentication.

There are two types of tokens: Test and Live:

Test Generates watermarked images and will not count against your plan usage.
Live Generates un-watermarked images and will count against your plan usage.

If you are subscribed to a paid plan, you will be able to generate both Test and Live token types.

If you are not subscribed to a paid plan, any tokens you generate will be Test tokens. But fear not! You can upgrade to a paid plan to access Live tokens.

Top

Handwritings

Our handwriting catalog contains a huge variety of real handwritings, any of which can be used in your application. The list can be obtained by calling the GET /handwritings endpoint.

Each handwriting in our catalog includes a title and several "rating" values for different attributes. For example, handwritings with high values for rating_neatness might look neat, careful, and consistent while handwritings with lower values might appear messy, casual, or rushed.

Top

Image Formats

We currently support PNG as the raster format (for digital products) and PDF as the vector format (for printed products). All images have transparent backgrounds.

Top

Distance Strings

Several parameters to the render calls are of type distance string. These will look familiar to developers who have written CSS. These are of the form 20px, 72pt, or 1.5in, for example. PNG requires that all distance strings are in units of px, and PDF requires units of pt, in, mm, or cm.

Top

Dimensions

The parameters width and height set the dimensions of the image. Each should be provided as distance strings .

Try a Live Demo

height and width may also be set to auto to automatically resize the image to contain the text.

Try a Live Demo
Try a Live Demo
Top

Handwriting Size

The height of the handwriting can be set with the handwriting_size parameter, provided as a distance string.

Additionally, this may be set to auto to automatically resize the text to fit within the image dimensions. When using this option, the image dimensions must be fixed (not auto).

With a short sample of text, the handwriting size will be increased to fill the space:

Try a Live Demo

As the text length changes, the handwriting is resized to fit:

Try a Live Demo

If the text is too long for the resulting text to be readable within the given space, an error will be returned: 

{
  "errors": [
    {
      "error": "text will not fit legibly in given dimensions",
      "field": "text"
    }
  ]
}
Top

Handwriting Color

handwriting_color controls the color of the handwritten text. Can be provided as RGB (#RRGGBB) or CMYK ((C, M, Y, K)). RGB is required for PNG and CMYK is required for PDF. Both default to black if not specified.

Try a Live Demo
Top

Randomization

Normally, every time you request an image with the same parameters, the result will change. This is due to the variable nature of handwriting.

Try a Live Demo
Try a Live Demo

In cases where a repeatable image is desired, the random_seed parameter can be provided. If this parameter is included and positive, the returned image will always be the same for the given set of parameters.

Try a Live Demo
Top

Rate Limiting

Calls to the API are rate limited. Check your rate limit status by reading the X-Ratelimit-* headers in the response to any authenticated call.

X-RateLimit-Limit The number of requests allowed per hour.
X-RateLimit-Remaining The number of requests remaining in the current period.

Contact us if you would like your rate limit increased.

Top

Example Code

Having trouble getting started? Check out our Github repository full of example code for calling the API.

Top

Libraries

Official Libraries:

Community Libraries:

Top

API Reference

GET /handwritings

Gets a list of handwritings.

Parameters

limit integer

number of items to fetch

defaults to 200 , minimum is 1 , maximum is 1000

offset integer

starting point in data set

defaults to 0

order_dir string

order direction

defaults to asc , value must be one of: asc , desc

order_by string

order field

defaults to id , value must be one of: id , title , date_created , date_modified , rating_neatness , rating_cursivity , rating_embellishment , rating_character_width

Responses

200 (application/json)
[
  {
    "id": "2D5QW0F80001",
    "title": "Molly",
    "date_created": "2015-04-30T21:27:45.979398Z",
    "date_modified": "2016-01-06T20:28:09.55861Z",
    "rating_neatness": 1459,
    "rating_cursivity": 1286,
    "rating_embellishment": 1367,
    "rating_character_width": 1339
  },
  {
    "id": "2D5S18M00002",
    "title": "Winters",
    "date_created": "2015-04-30T21:30:18.575741Z",
    "date_modified": "2015-12-16T15:18:27.777815Z",
    "rating_neatness": 1425,
    "rating_cursivity": 1319,
    "rating_embellishment": 1373,
    "rating_character_width": 1236
  },
  ...
]
429 (application/json)
{
  "errors": [
    {
      "error": "rate limit exceeded"
    }
  ]
}
Top

GET /handwritings/{id}

Get a handwriting.

Parameters

id string required

Handwriting ID

Responses

200 (application/json)
{
  "id": "2D5QW0F80001",
  "title": "Molly",
  "date_created": "2015-04-30T21:27:45.979398Z",
  "date_modified": "2016-01-06T20:28:09.55861Z",
  "rating_neatness": 1459,
  "rating_cursivity": 1286,
  "rating_embellishment": 1367,
  "rating_character_width": 1339
}
404 (application/json)
{
  "errors": [
    {
      "error": "not found"
    }
  ]
}
429 (application/json)
{
  "errors": [
    {
      "error": "rate limit exceeded"
    }
  ]
}
Top

GET /render/png

Render text in the specified handwriting, as a PNG image.

Parameters

handwriting_id string required

The ID of the handwriting to use.

text string required

maximum length is 9000 characters

handwriting_size distance string

The size of the handwriting, from baseline to cap height. May be set to auto to determine the size automatically based on the width and height.

defaults to 20px , minimum is 0px , maximum is 9000px

handwriting_color string

The color of the handwriting expressed as #RRGGBB.

defaults to #000000

width distance string

Width of the image. May be set to auto to determine the width automatically based on the text.

defaults to 504px , minimum is 0px , maximum is 9000px

height distance string

Height of the image. May be set to auto to determine the height automatically based on the text.

defaults to 360px , minimum is 0px , maximum is 9000px

min_padding distance string experimental

Centers the block of text within the image, preserving at least min_padding around all four edges of the image.

line_spacing float

Amount of vertical space for each line, provided as a multiplier of handwriting_size.

defaults to 1.5 , minimum is 0.0 , maximum is 5.0

line_spacing_variance float

Amount to randomize spacing between lines, provided as a multiplier. Example: 0.1 means the space between lines will vary by +/- 10%.

defaults to 0.0 , minimum is 0.0 , maximum is 1.0

word_spacing_variance float

Amount to randomize spacing between words, provided as a multiplier. Example: 0.1 means the space between words will vary by +/- 10%.

defaults to 0.0 , minimum is 0.0 , maximum is 1.0

random_seed integer

Set this to a positive number to get a repeatable image. If this parameter is included and positive, the returned image should always be the same for the given set of parameters.

defaults to -1

Responses

200 (image/png)
BINARY DATA
400 (application/json)
{
  "errors": [
    {
      "error": "text contains characters that do not exist in the selected handwriting",
      "field": "text",
      "missing_characters": [
        {
          "positions": [
                        5
          ],
          "character": "^",
          "hex": "005E",
          "name": "CIRCUMFLEX ACCENT"
        }
      ]
    }
  ]
}
429 (application/json)
{
  "errors": [
    {
      "error": "rate limit exceeded"
    }
  ]
}
Top

GET /render/pdf

Render text in the specified handwriting as a PDF file.

Parameters

handwriting_id string required

The ID of the handwriting to use.

text string required

maximum length is 9000 characters

handwriting_size distance string

The size of the handwriting, from baseline to cap height. May be set to auto to determine the size automatically based on the width and height.

defaults to 20pt , minimum is 0in , maximum is 100in

handwriting_color string

The color of the handwriting expressed as (C,M,Y,K).

defaults to (0, 0, 0, 1)

width distance string

Width of the image. May be set to auto to determine the width automatically based on the text.

defaults to 7in , minimum is 0in , maximum is 100in

height distance string

Height of the image. May be set to auto to determine the height automatically based on the text.

defaults to 5in , minimum is 0in , maximum is 100in

min_padding distance string experimental

Centers the block of text within the image, preserving at least min_padding around all four edges of the image.

line_spacing float

Amount of vertical space for each line, provided as a multiplier of handwriting_size.

defaults to 1.5 , minimum is 0.0 , maximum is 5.0

line_spacing_variance float

Amount to randomize spacing between lines, provided as a multiplier. Example: 0.1 means the space between lines will vary by +/- 10%.

defaults to 0.0 , minimum is 0.0 , maximum is 1.0

word_spacing_variance float

Amount to randomize spacing between words, provided as a multiplier. Example: 0.1 means the space between words will vary by +/- 10%.

defaults to 0.0 , minimum is 0.0 , maximum is 1.0

random_seed integer

Set this to a positive number to get a repeatable image. If this parameter is included and positive, the returned image should always be the same for the given set of parameters.

defaults to -1

Responses

200 (application/pdf)
BINARY DATA
400 (application/json)
{
  "errors": [
    {
      "error": "text contains characters that do not exist in the selected handwriting",
      "field": "text",
      "missing_characters": [
        {
          "positions": [
                        5
          ],
          "character": "^",
          "hex": "005E",
          "name": "CIRCUMFLEX ACCENT"
        }
      ]
    }
  ]
}
429 (application/json)
{
  "errors": [
    {
      "error": "rate limit exceeded"
    }
  ]
}
Top