Python Library

The library wraps the APIs so you can parse and extract documents from Python. The library is published as the landingai-ade package and generated from the API specification. The Gen2 APIs live under the client.v2 sub-client. It exposes both processing modes: async jobs through client.v2.parse_jobs and client.v2.extract_jobs, and synchronous calls through client.v2.parse and client.v2.extract. Jobs accept larger documents, default to the lower-consumption standard service tier, and suit automated pipelines and background work. See Sync vs Async Processing.

Install the Library

Requires Python 3.9 or later.

pip install landingai-ade

Set Your API Key

The library reads your API key from the VISION_AGENT_API_KEY environment variable. Generate an API key first, then set it using any of the methods below. Do not hard-code your API key in source files.

Method 1: Set the API Key as an Environment Variable

Set the environment variable. To persist the key across sessions on macOS or Linux, add the export command to your shell profile (.zshrc or .bashrc), then run source ~/.zshrc.
export VISION_AGENT_API_KEY="<your-api-key>"
set "VISION_AGENT_API_KEY=<your-api-key>"
$env:VISION_AGENT_API_KEY="<your-api-key>"
Initialize the client. It reads the VISION_AGENT_API_KEY environment variable automatically:
from landingai_ade import LandingAIADE client = LandingAIADE()

Method 2: Store the API Key in a .env File

Store your API key in a .env file. The library reads the key from the environment; it does not load .env files on its own, so use python-dotenv to load the file.

Install the python-dotenv package:
pip install python-dotenv
Create a .env file in your project root and add your API key:
VISION_AGENT_API_KEY=<your-api-key>

Load the .env file before you initialize the client:

from dotenv import load_dotenv
from landingai_ade import LandingAIADE

load_dotenv()  # Populates the environment from .env.

client = LandingAIADE()

Method 3: Set the API Key in a Notebook

In IPython-based notebooks (Jupyter, JupyterLab, Google Colab, or Kaggle), set the key for the current session with the %env magic command. The key is cleared when the kernel restarts, and it is visible in the notebook file if you share or commit it.

In a notebook cell, set the environment variable:
%env VISION_AGENT_API_KEY=<your-api-key>

Initialize the client in a later cell:

from landingai_ade import LandingAIADE

client = LandingAIADE()

API Key Precedence

If the API key is set in more than one place, the library resolves it in this order (the first match wins):

The apikey passed to the client constructor.
The VISION_AGENT_API_KEY environment variable, whether you set it directly or loaded it from a .env file. A value already set in your environment is not overridden by a .env file.

For help with missing-key errors, keys that fail to load, or keys that resolve to the wrong account, see Troubleshoot API Key Issues.

Initialize the Client

Create a client. It reads VISION_AGENT_API_KEY from the environment automatically.

from landingai_ade import LandingAIADE

client = LandingAIADE()

By default, the library uses the US endpoints. If your API key is from the EU region, set the environment parameter to eu. API keys are region-specific: an EU key works only with the EU environment.

from landingai_ade import LandingAIADE

client = LandingAIADE(environment="eu")

For more about using in the EU, see European Union (EU).

Parse a Document

Use client.v2.parse_jobs to convert a document into Markdown, a structure tree, and per-element grounding. The sub-client exposes create, get, list, and wait. The wait method polls until the job reaches a terminal state and returns the finished job. Pass a local file as a Path with the document parameter, or a remote file with document_url. Setting service_tier to standard runs the job in the lane that consumes half the credits of priority. A finished job carries the parse output in result, a V2ParseResponse with markdown, structure, and metadata. For the full workflow and parameters, see Parse Asynchronously.

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

Extract Data

Use client.v2.extract_jobs to pull structured fields from parsed Markdown. Provide the Markdown as a string with markdown (or a remote URL with markdown_url) and a schema. The schema parameter accepts a Pydantic model, a dictionary, or a JSON string. A finished job carries the extraction in result, a V2ExtractResult with extraction, extraction_metadata, markdown, and metadata. For the full workflow and parameters, see Asynchronous Extraction.

from pathlib import Path
from pydantic import BaseModel, Field
from landingai_ade import LandingAIADE

class Financials(BaseModel):
    revenue: str = Field(description="Q1 2024 revenue")

client = LandingAIADE()

# Parse first to get Markdown, then extract.
parse_job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
parsed = client.v2.parse_jobs.wait(parse_job.job_id)

extract_job = client.v2.extract_jobs.create(
    markdown=parsed.result.markdown,
    schema=Financials,
    service_tier="standard",
)
extracted = client.v2.extract_jobs.wait(extract_job.job_id)
print(extracted.result.extraction)

Set the Model Version

The model parameter is optional. When you omit it, the API uses the latest model. To select a family or pin a version, pass a model string such as dpt-3-verity, or a dated snapshot. See Parsing Models. Responses parsed with dpt-3-verity include a confidence score on each word-level atomic_grounding entry. See Word Confidence Scores.

from pathlib import Path

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)

Save Output to a File

The job create methods do not accept save_to. To keep a job’s output, write result to a file yourself, or pass output_save_url on create to have deliver the result straight to your own storage. See Save Parsed Output to a URL. The synchronous parse and extract methods take an optional save_to parameter instead, which writes the full response to a JSON file. Pass it a directory to use an auto-generated file name, or a path ending in .json to choose the exact file.

from pathlib import Path

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    service_tier="standard",
)
done = client.v2.parse_jobs.wait(job.job_id)

Path("parse-output.json").write_text(done.result.model_dump_json(indent=2))

Handle Errors

The synchronous parse and extract methods raise V2SyncTimeoutError if the request exceeds the server’s synchronous time limit (HTTP 504). For large documents, use the async jobs interface instead. When a parse partially succeeds (some pages fail), the API returns the full response with an HTTP 206 status, and the failed pages are listed in metadata. See Troubleshoot Parsing. The job wait method returns the finished job regardless of outcome, so check job.status. To raise instead when a job fails, pass raise_on_failure=True, which raises JobFailedError. If a job does not finish within the timeout, wait raises JobWaitTimeoutError.

from pathlib import Path
from landingai_ade import LandingAIADE
from landingai_ade.lib.v2_errors import JobFailedError, JobWaitTimeoutError

client = LandingAIADE()

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    service_tier="standard",
)
try:
    done = client.v2.parse_jobs.wait(job.job_id, timeout=600, raise_on_failure=True)
    print(done.result.markdown)
except JobFailedError as error:
    print(f"Job failed: {error}")
except JobWaitTimeoutError:
    print("Job did not finish in time; poll again with parse_jobs.get().")

Additional Resources

Python library on GitHub. The README covers client configuration not documented here, including retries, timeouts, the async client, logging, raw response access, and custom requests.
API reference
Parse Documents and Extract Data

Get Started

Client Libraries

Parsing

Extraction

Grounding

General

Security

Administration

Pricing & Credits

Install the Library

Set Your API Key

Method 1: Set the API Key as an Environment Variable

Method 2: Store the API Key in a .env File

Method 3: Set the API Key in a Notebook

API Key Precedence

Initialize the Client

Parse a Document

Extract Data

Set the Model Version

Save Output to a File

Handle Errors

Additional Resources

​Install the Library

​Set Your API Key

​Method 1: Set the API Key as an Environment Variable

​Method 2: Store the API Key in a .env File

​Method 3: Set the API Key in a Notebook

​API Key Precedence

​Initialize the Client

​Parse a Document

​Extract Data

​Set the Model Version

​Save Output to a File

​Handle Errors

​Additional Resources

Install the Library

Set Your API Key

Method 1: Set the API Key as an Environment Variable

Method 2: Store the API Key in a .env File

Method 3: Set the API Key in a Notebook

API Key Precedence

Initialize the Client

Parse a Document

Extract Data

Set the Model Version

Save Output to a File

Handle Errors

Additional Resources