Convert Document - Datalab Documentation

POST

api

convert

Convert Document

import requests

url = "https://www.datalab.to/api/v1/convert"

files = { "file.0": ("example-file", open("example-file", "rb")) }
payload = {
    "file_url": "<string>",
    "mode": "fast",
    "max_pages": "123",
    "page_range": "<string>",
    "paginate": "false",
    "add_block_ids": "false",
    "include_markdown_in_chunks": "false",
    "disable_image_extraction": "false",
    "disable_image_captions": "false",
    "word_bboxes": "false",
    "fence_synthetic_captions": "false",
    "output_format": "<string>",
    "token_efficient_markdown": "false",
    "skip_cache": "false",
    "save_checkpoint": "false",
    "additional_config": "<string>",
    "workflowstepdata_id": "123",
    "extras": "<string>",
    "webhook_url": "<string>",
    "processing_location": "<string>",
    "eval_rubric_id": "123",
    "force_new": "false",
    "model_override_settings": "<string>",
    "file": "<string>"
}
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

curl --request POST \
  --url https://www.datalab.to/api/v1/convert \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'file_url=<string>' \
  --form mode=fast \
  --form max_pages=123 \
  --form 'page_range=<string>' \
  --form paginate=false \
  --form add_block_ids=false \
  --form include_markdown_in_chunks=false \
  --form disable_image_extraction=false \
  --form disable_image_captions=false \
  --form word_bboxes=false \
  --form fence_synthetic_captions=false \
  --form 'output_format=<string>' \
  --form token_efficient_markdown=false \
  --form skip_cache=false \
  --form save_checkpoint=false \
  --form 'additional_config=<string>' \
  --form workflowstepdata_id=123 \
  --form 'extras=<string>' \
  --form 'webhook_url=<string>' \
  --form 'processing_location=<string>' \
  --form eval_rubric_id=123 \
  --form force_new=false \
  --form 'model_override_settings=<string>' \
  --form 'file=<string>' \
  --form file.0='@example-file'

const form = new FormData();
form.append('file_url', '<string>');
form.append('mode', 'fast');
form.append('max_pages', '123');
form.append('page_range', '<string>');
form.append('paginate', 'false');
form.append('add_block_ids', 'false');
form.append('include_markdown_in_chunks', 'false');
form.append('disable_image_extraction', 'false');
form.append('disable_image_captions', 'false');
form.append('word_bboxes', 'false');
form.append('fence_synthetic_captions', 'false');
form.append('output_format', '<string>');
form.append('token_efficient_markdown', 'false');
form.append('skip_cache', 'false');
form.append('save_checkpoint', 'false');
form.append('additional_config', '<string>');
form.append('workflowstepdata_id', '123');
form.append('extras', '<string>');
form.append('webhook_url', '<string>');
form.append('processing_location', '<string>');
form.append('eval_rubric_id', '123');
form.append('force_new', 'false');
form.append('model_override_settings', '<string>');
form.append('file', '<string>');
form.append('file.0', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://www.datalab.to/api/v1/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.datalab.to/api/v1/convert"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mode\"\r\n\r\nfast\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"max_pages\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page_range\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"paginate\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"add_block_ids\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"include_markdown_in_chunks\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"disable_image_extraction\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"disable_image_captions\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"word_bboxes\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fence_synthetic_captions\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_format\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"token_efficient_markdown\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"skip_cache\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"save_checkpoint\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"additional_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflowstepdata_id\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extras\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"processing_location\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eval_rubric_id\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"force_new\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_override_settings\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "request_id": "<string>",
  "request_check_url": "<string>",
  "success": true,
  "error": "<string>",
  "versions": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Cookies

wos-session

string

datalab_active_team

string

Body

multipart/form-data

file_url

string | null

Optional file URL (http/https). If provided, the server will download and process it.

mode

string

default:fast

Which output mode to use. Valid values: 'fast' (lowest latency), 'balanced' (balanced accuracy and latency), 'accurate' (highest accuracy).

max_pages

integer | null

The maximum number of pages in the document to convert.

page_range

string | null

The page range to convert, comma separated like 0,5-10,20. Overrides max_pages if provided.

paginate

boolean

default:false

Whether to paginate the output. Each page will be separated by a horizontal rule with the page number.

add_block_ids

boolean

default:false

Add data-block-id attributes to HTML elements for citation tracking. Only applies when output_format includes 'html'.

include_markdown_in_chunks

boolean

default:false

Include markdown field in chunks and JSON output.

disable_image_extraction

boolean

default:false

Disable image extraction from the document.

disable_image_captions

boolean

default:false

Disable synthetic image captions/descriptions in output.

word_bboxes

boolean

default:false

When enabled, predict per-word bounding boxes with confidence scores for each page. Each word is inlined into the HTML output as a span carrying data-bbox and data-confidence attributes (markdown output strips these).

fence_synthetic_captions

boolean

default:false

Wrap synthetic image captions with HTML comment markers for easy identification/removal.

output_format

string | null

The output format. Can be 'json', 'html', 'markdown', or 'chunks'. Defaults to 'markdown'. Comma separate multiple formats.

token_efficient_markdown

boolean

default:false

Optimize markdown for LLM token usage (compact tables, single-space indents).

skip_cache

boolean

default:false

Skip the cache and re-run the conversion.

save_checkpoint

boolean

default:false

Save a checkpoint after conversion. The checkpoint_id in the response can be used with /extract or /segment to skip re-parsing.

additional_config

string | null

Additional configuration as a JSON string. Supported keys: 'keep_pageheader_in_output', 'keep_pagefooter_in_output', 'keep_spreadsheet_formatting'.

workflowstepdata_id

integer | null

Optional workflow step data ID to associate with this request.

extras

string | null

Comma-separated list of extra features: 'track_changes', 'chart_understanding', 'table_cell_bboxes' (per-cell bounding boxes for each table, instead of one box for the whole table; includes word bounding boxes), 'list_item_bboxes' (per-item bounding boxes for each list or list group, instead of one box for the whole list; includes word bounding boxes), 'extract_links', 'infographic', 'new_block_types'. ('table_row_bboxes' is deprecated; use 'table_cell_bboxes'.)

webhook_url

string | null

Optional webhook URL to call when the request is complete.

processing_location

string | null

Optional residency region override (e.g. us, eu). When provided, use file_url or direct-upload; multipart uploads are rejected. When omitted, the request uses the team's configured residency and profile.

eval_rubric_id

integer | null

Optional eval rubric ID to run evaluation after conversion.

force_new

boolean

default:false

Internal: force Modal backend.

model_override_settings

string | null

file

file | null

Input PDF, word document, powerpoint, or image file, uploaded as multipart form data. Images must be png, jpg, or webp format.

Response

Successful Response

request_id

string

required

The ID of the request. This ID can be used to check the status of the request.

request_check_url

string

required

The URL to check the status of the request and get results.

success

boolean

default:true

Whether the request was successful.

error

string | null

If the request was not successful, this will contain an error message.

versions

A dictionary of the versions of the libraries used in the request.

Extract Structured DataExtract structured data from a document using a JSON schema. Provide a file for end-to-end processing, or a checkpoint_id from a previous /convert call to skip re-parsing.

⌘I

Convert Document

import requests

url = "https://www.datalab.to/api/v1/convert"

files = { "file.0": ("example-file", open("example-file", "rb")) }
payload = {
    "file_url": "<string>",
    "mode": "fast",
    "max_pages": "123",
    "page_range": "<string>",
    "paginate": "false",
    "add_block_ids": "false",
    "include_markdown_in_chunks": "false",
    "disable_image_extraction": "false",
    "disable_image_captions": "false",
    "word_bboxes": "false",
    "fence_synthetic_captions": "false",
    "output_format": "<string>",
    "token_efficient_markdown": "false",
    "skip_cache": "false",
    "save_checkpoint": "false",
    "additional_config": "<string>",
    "workflowstepdata_id": "123",
    "extras": "<string>",
    "webhook_url": "<string>",
    "processing_location": "<string>",
    "eval_rubric_id": "123",
    "force_new": "false",
    "model_override_settings": "<string>",
    "file": "<string>"
}
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

curl --request POST \
  --url https://www.datalab.to/api/v1/convert \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'file_url=<string>' \
  --form mode=fast \
  --form max_pages=123 \
  --form 'page_range=<string>' \
  --form paginate=false \
  --form add_block_ids=false \
  --form include_markdown_in_chunks=false \
  --form disable_image_extraction=false \
  --form disable_image_captions=false \
  --form word_bboxes=false \
  --form fence_synthetic_captions=false \
  --form 'output_format=<string>' \
  --form token_efficient_markdown=false \
  --form skip_cache=false \
  --form save_checkpoint=false \
  --form 'additional_config=<string>' \
  --form workflowstepdata_id=123 \
  --form 'extras=<string>' \
  --form 'webhook_url=<string>' \
  --form 'processing_location=<string>' \
  --form eval_rubric_id=123 \
  --form force_new=false \
  --form 'model_override_settings=<string>' \
  --form 'file=<string>' \
  --form file.0='@example-file'

const form = new FormData();
form.append('file_url', '<string>');
form.append('mode', 'fast');
form.append('max_pages', '123');
form.append('page_range', '<string>');
form.append('paginate', 'false');
form.append('add_block_ids', 'false');
form.append('include_markdown_in_chunks', 'false');
form.append('disable_image_extraction', 'false');
form.append('disable_image_captions', 'false');
form.append('word_bboxes', 'false');
form.append('fence_synthetic_captions', 'false');
form.append('output_format', '<string>');
form.append('token_efficient_markdown', 'false');
form.append('skip_cache', 'false');
form.append('save_checkpoint', 'false');
form.append('additional_config', '<string>');
form.append('workflowstepdata_id', '123');
form.append('extras', '<string>');
form.append('webhook_url', '<string>');
form.append('processing_location', '<string>');
form.append('eval_rubric_id', '123');
form.append('force_new', 'false');
form.append('model_override_settings', '<string>');
form.append('file', '<string>');
form.append('file.0', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://www.datalab.to/api/v1/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.datalab.to/api/v1/convert"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mode\"\r\n\r\nfast\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"max_pages\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"page_range\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"paginate\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"add_block_ids\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"include_markdown_in_chunks\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"disable_image_extraction\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"disable_image_captions\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"word_bboxes\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fence_synthetic_captions\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_format\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"token_efficient_markdown\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"skip_cache\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"save_checkpoint\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"additional_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflowstepdata_id\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extras\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"processing_location\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"eval_rubric_id\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"force_new\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model_override_settings\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file.0\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "request_id": "<string>",
  "request_check_url": "<string>",
  "success": true,
  "error": "<string>",
  "versions": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}