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 v2 APIs live under the client.v2 sub-client (for example, client.v2.parse).

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 to convert a document into Markdown, a structure tree, and per-element grounding. Pass a local file as a Path with the document parameter, or a remote file with document_url.

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

response = client.v2.parse(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
)
print(response.markdown)

The response is a V2ParseResponse with markdown, structure, and metadata. For the full parameters and response shape, see Parse Documents.

Extract Data

Use client.v2.extract 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.

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_response = client.v2.parse(document=Path("document.pdf"), model="dpt-3-pro-latest")

extract_response = client.v2.extract(
    markdown=parse_response.markdown,
    schema=Financials,
)
print(extract_response.extraction)

The response is a V2ExtractResult with extraction, extraction_metadata, markdown, and metadata. For the full parameters and response shape, see Extract Data.

Process Documents Asynchronously

For large documents or long-running work, use the async jobs interface. The client exposes parse_jobs and extract_jobs, each with create, get, list, and wait methods. The wait method polls until the job reaches a terminal state and returns the finished job.

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.parse_jobs.create(document=Path("document.pdf"))
done = client.v2.parse_jobs.wait(job.job_id)
print(done.result.markdown)

Set the optional service_tier parameter on create to "priority" for faster turnaround, or omit it to run on the standard tier. For the full workflow, service tiers, and saving output to a URL, see Parse Asynchronously and Asynchronous Extraction.

Set the Model Version

The model parameter is optional. When you omit it, the API uses the latest model. To pin a specific version, pass a model string such as dpt-3-pro-latest or a dated snapshot. See Model Version.

from pathlib import Path

response = client.v2.parse(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
)

Save Output to a File

Pass the optional save_to parameter on parse or extract to write the full response to a JSON file. Pass a directory to use an auto-generated file name, or a path ending in .json to choose the exact file. The async job create methods do not accept save_to.

from pathlib import Path

response = client.v2.parse(
    document=Path("document.pdf"),
    save_to="./output",
)

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"))
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

General

Security

Administration

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

Process Documents Asynchronously

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

​Process Documents Asynchronously

​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

Process Documents Asynchronously

Set the Model Version

Save Output to a File

Handle Errors

Additional Resources