Dewarping¶

POST /api/dewarp

Upload a document image, receive the dewarped version. Costs 1 credit.

Request¶

Send the image as multipart/form-data with a file field:

curl -s https://page-dewarp-api.louismmx.workers.dev/api/dewarp \
  -H "Authorization: Bearer pdw_YOUR_API_KEY" \
  -F "file=@page.jpg" \
  --output dewarped.png

Optional request headers¶

Header	Default	Description
`X-Dewarp-Params`	`{}`	JSON object of processing parameters. See Parameters.
`X-Dewarp-Include`	`result`	Comma-separated list of metadata to include in response headers.

X-Dewarp-Include values¶

Value	Content
`result`	JSON dewarp parameters (rotation vector, cubic coefficients, page dimensions, etc.)
`stdout`	CLI standard output (config, timing, optimisation statistics)
`stderr`	CLI standard error
`none`	No metadata headers — just the image

Combine with commas: result,stdout,stderr

Response¶

Body: the dewarped image in the requested format (PNG by default).

Headers:

Header	Encoding	Present when
`X-Credits-Remaining`	plain text	Always
`X-Dewarp-Result`	base64	`result` in `X-Dewarp-Include`
`X-Dewarp-Stdout`	base64	`stdout` in `X-Dewarp-Include`
`X-Dewarp-Stderr`	base64	`stderr` in `X-Dewarp-Include`

Decoding metadata headers¶

The metadata headers are base64-encoded to avoid HTTP header formatting issues.

# Save headers while downloading the image
curl -s .../api/dewarp \
  -H "Authorization: Bearer pdw_..." \
  -H 'X-Dewarp-Include: result,stdout' \
  -F "file=@page.jpg" \
  -D headers.txt --output dewarped.png

# Decode the dewarp parameters
grep x-dewarp-result headers.txt | cut -d' ' -f2 | tr -d '\r' | base64 -d | jq .

Dewarp result structure¶

The X-Dewarp-Result header decodes to a JSON object:

{
  "input_file": "input.tif",
  "output_file": "input_thresh.png",
  "rotation_vector": [-0.0019, 0.0030, -0.0136],
  "translation_vector": [-0.7243, -1.0011, 1.2017],
  "cubic_params": [0.0027, 0.0105],
  "page_dims": [1.4219, 2.0231],
  "corners": [[[-0.723, -1.000]], [[0.699, -1.016]], [[0.723, 1.000]], [[-0.699, 1.016]]],
  "image_shape": [5492, 3839, 3],
  "small_shape": [686, 480, 3]
}

Field	Description
`rotation_vector`	3-element Rodrigues rotation vector of the fitted camera pose
`translation_vector`	3-element translation of the camera
`cubic_params`	2 cubic slope parameters defining the page curvature model
`page_dims`	Normalised width and height of the detected page
`corners`	4 corner points of the detected page in normalised coordinates
`image_shape`	Original image dimensions (height, width, channels)
`small_shape`	Downsampled dimensions used for contour detection

Error responses¶

Status	Meaning	Action
`401`	Missing or invalid authentication	Check your API key or JWT
`402`	Insufficient credits	Purchase more credits via `/api/checkout`
`422`	Processing failed	Image may be unsuitable (no text detected, corrupt file). Check the error detail.
`502`	Processing backend unreachable	Retry after a few seconds. If persistent, the service may be experiencing issues.

Credit deduction¶

Credits are deducted only after successful processing. If the request fails for any reason, no credit is charged.