Conversion API

Create a token

An administrator creates client tokens from the dashboard. Sign in, open Dashboard → API, and choose Create token. Copy the secret when it is shown. Later lists include only the prefix. Set the token's allowed origins to the site that will call the API, for example https://example.com.

Send the token on every request as Authorization: Bearer <token>. Image conversion and quota also send X-Client-Endpointset to that origin, with no path. PDF conversion uses the same bearer token and does not read that header. Image conversion and PDF conversion share the token's quota.

Quota

GET /v1/usage returns the token's byte quota.

curl "https://api.drunkwallaby.com/v1/usage" \
  -H "Authorization: Bearer hk_example_replace_me" \
  -H "X-Client-Endpoint: https://example.com"

200

{
  "quota_bytes": 104857600,
  "used_bytes": 0,
  "remaining_bytes": 104857600
}

Convert an image

POST /v1/convert accepts one JPEG, PNG, WebP, GIF, or HEIC body. Query parameters are input, output (jpeg, png, webp, gif, or heic), and max_mb from 0.5 to 8. The body is the raw file, and Content-Type is the input media type. A successful response is the converted image, not JSON.

curl -X POST "https://api.drunkwallaby.com/v1/convert?input=heic&output=jpeg&max_mb=1.5" \
  -H "Authorization: Bearer hk_example_replace_me" \
  -H "X-Client-Endpoint: https://example.com" \
  -H "Content-Type: image/heic" \
  --data-binary @photo.heic \
  --output photo.jpg

200 Content-Type: image/jpeg, body is the JPEG file.

Convert to PDF

POST /v1/convert/pdf?max_mb=1.5 builds one PDF. max_mbis required and is a positive number of megabytes, the output cap. This site's converter uses 0.5 to 8. There is no upload grant for PDF: grants only accept jpeg, png, webp, gif, and heic.

Send up to 16 images as multipart/form-data, one image per part, in page order. Each part body is one page. The examples use the field name file. Accepted images are JPEG, PNG, WebP, and HEIC. GIF is not accepted. A single image can instead be the raw body. Plain text is text/plain and must be UTF-8 (charset=utf-8 or us-ascii). A Word document is application/vnd.openxmlformats-officedocument.wordprocessingml.document, and the body must be a docx zip. HTML (text/html or application/xhtml+xml) is rejected with 415 unsupported_input. More than 16 pages is 400 too_many_pages. A successful response is application/pdf.

Images

curl -X POST "https://api.drunkwallaby.com/v1/convert/pdf?max_mb=1.5" \
  -H "Authorization: Bearer hk_example_replace_me" \
  -F "file=@page-1.jpg" \
  -F "file=@page-2.png" \
  --output pages.pdf

Plain text

curl -X POST "https://api.drunkwallaby.com/v1/convert/pdf?max_mb=1.5" \
  -H "Authorization: Bearer hk_example_replace_me" \
  -H "Content-Type: text/plain; charset=utf-8" \
  --data-binary @notes.txt \
  --output notes.pdf

Word

curl -X POST "https://api.drunkwallaby.com/v1/convert/pdf?max_mb=1.5" \
  -H "Authorization: Bearer hk_example_replace_me" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  --data-binary @letter.docx \
  --output letter.pdf

200 Content-Type: application/pdf, body is the PDF file.

Errors

Failures are JSON with error and message. A missing or wrong token is 401 on every endpoint, including image conversion and PDF conversion.

{
  "error": "unauthorized",
  "message": "Missing or invalid credentials."
}

{
  "error": "payload_too_large",
  "message": "Request body exceeds the input limit."
}

{
  "error": "too_many_pages",
  "message": "PDF conversion accepts at most 16 pages."
}

{
  "error": "unsupported_input",
  "message": "HTML is not converted. This server does not run a headless browser. Send JPEG, PNG, WebP, HEIC, plain text, or DOCX."
}

{
  "error": "subject_limited",
  "message": "This subject has reached its daily conversion limit."
}