Skip to content

Get started

Convert page images of print books into accessible ebooks.


NOTE: BookBridge is ALPHA software. The interface described in the documentation will likely change.

This tutorial will guide you through the process of converting a set of page images into an accessible ebook (EPUBv3) using the BookBridge API. The conversion process takes about five minutes. It may be broken down into three steps:

  1. Creating a conversion job by uploading page images to the BookBridge server.
  2. Checking on the status of the conversion job.
  3. Retrieving the finished ebook (EPUBv3).

The rest of this document describes these steps in detail.

Requirements

This tutorial assumes you're familiar with REST APIs and that you have the following in hand:

  • Page images of a book.

    Images should be at least 300 DPI. This tutorial assumes they've been gathered into a single PDF. For examples of PDFs packaged in this way, see the Page Images for Testing.

  • A Glyphlab API key. You can register for an account if you haven't yet.

Create a conversion job

Create a conversion job by uploading page images using the following curl command:

curl https://api.glyphlab.xyz/v1/jobs \
    -u "sk_test_b686f1b8206e7b60c935:" \
    -F file="@/path/to/a/book.pdf"

The command above assumes your PDF may be found at /path/to/a/book.pdf. The HTTP request above may be made a variety of ways. You need not use curl if you prefer to use a programming language such as Python or Go. Most programming languages support making the request. Note that because a file is being uploaded, the request sends data using multipart/form-data.

This request will return a job that will look something like the following:

{
  "id": "job_b4ee8c",
  "created": 1741219200,
  "expires_at": 1743984000,
  "status": "processing"
}

Note the job's id. You'll need this to check the job's status.

Check the job's status

Now we wait for the job to complete. Most conversion jobs finish within five minutes. Long books require more time.

You can check the status of a job by making a request using the job's id:

curl https://api.glyphlab.xyz/v1/jobs/job_b4ee8c \
    -u "sk_test_b686f1b8206e7b60c935:"

If the job isn't complete you'll see that its status is processing. If the job is finished, you'll get a response that looks something like this:

{
  "id": "job_b4ee8c",
  "created": 1741219200,
  "expires_at": 1743984000,
  "status": "succeeded",
  "epub_url": "https://files.glyphlab.xyz/job_b4ee8c/book.epub"
}

Retrieve the ebook

Now we download the ebook.

When the conversion process has finished, the job is updated to include a url to the ebook. In the example above, the url is https://files.glyphlab.xyz/job_b4ee8c/book.epub. You can retrieve this file using any HTTP client. Note that you do need to provide your API key in order to download the file. Here's how you would retrieve the ebook using curl:

curl -O https://files.glyphlab.xyz/job_b4ee8c/book.epub \
    -u "sk_test_b686f1b8206e7b60c935:"

It's your responsibility to retrieve the ebook before the job expires. For your privacy, files associated with a job are permanently deleted when their associated job expires.