Inkspan › Guides › Translate PDF API

Translate PDF API

Translate an entire PDF into any language in one API call. Upload the document, name the target language, and get the translated text back as JSON — or a regenerated PDF.

Translation reads the PDF's text layer, translates it with a language model, and returns either JSON or a regenerated PDF. There is no glossary to configure and no per-language setup.

cURL

curl -X POST https://api.inkspan.dev/v1/translate \
  -H "X-API-Key: ink_live_..." \
  -F "file=@document.pdf" \
  -F "target_language=Spanish" \
  | jq .

Python

import requests

r = requests.post(
    'https://api.inkspan.dev/v1/translate',
    headers={'X-API-Key': 'ink_live_...'},
    files={'file': open('document.pdf', 'rb')},
    data={'target_language': 'Spanish'},
)
r.raise_for_status()
print(r.json())

Request parameters

Name	Type	Required	Description
`target_language`	string	yes	Language to translate into, e.g. `Spanish`.
`file`	file	no	A PDF to translate. Provide either `file` or `text`.
`text`	string	no	Raw text to translate instead of uploading a file.
`output`	string	no	`json` (default) returns translated text; `pdf` returns a regenerated PDF.

Response

With the default output=json:

{
  "target_language": "Spanish",
  "characters": 1840,
  "translated_text": "\u2026"
}

Things that catch people out

Provide exactly one of file or text. Sending neither returns 400.
A scanned PDF has no text layer to read, so there is nothing to translate — rasterise and OCR it first.
Output defaults to JSON. Pass output=pdf if you want a document back rather than a string.
The regenerated PDF carries the translated text, not the original layout. For layout-faithful output, translate to JSON and render it through your own template.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

Which languages are supported?

Any language the underlying model handles — pass the language name, such as Spanish, French, German, or Japanese.

Does it preserve the original formatting?

No. Text is extracted, translated, and re-rendered, so the original layout is not reproduced. Translate to JSON and use your own template if layout matters.

Can I translate plain text instead of a PDF?

Yes — send the text parameter instead of a file.

Get a free API key →