CustomVlmApiSettings

Settings for CustomVlmApi. Values fall back through three levels: document → SDK → built-in default. Writes target the document only when set on a document’s settings, otherwise the SDK globally when set on SdkSettings.

Tags: Advanced, Vision

from nutrient_sdk import CustomVlmApiSettings

Construction

# Per-document override
with Document.open("input.pdf") as doc:
    settings = doc.settings.custom_vlm_api_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)
SdkSettings.custom_vlm_api_settings.some_field = new_value

Settings are configured by writing to fields on the returned object. The settings property itself cannot be reassigned — doc.settings.custom_vlm_api_settings = other_settings is rejected.

Properties

api_endpoint

@property
def api_endpoint(self) -> str

@api_endpoint.setter
def api_endpoint(self, value: str) -> None

API endpoint URL for OpenAI-compatible chat completions.

Type: str

Default: "http://localhost:1234/v1"

api_key

@property
def api_key(self) -> str

@api_key.setter
def api_key(self, value: str) -> None

API key for authentication with the VLM service.

Type: str

Default: string.Empty

batch_size

@property
def batch_size(self) -> int

@batch_size.setter
def batch_size(self, value: int) -> None

Number of zone images to include per VLM API call.

Type: int

Default: 8

classification_strategy

@property
def classification_strategy(self) -> VlmClassificationStrategy

@classification_strategy.setter
def classification_strategy(self, value: VlmClassificationStrategy) -> None

Strategy for how zones are sent to the VLM for classification.

Type: VlmClassificationStrategy

Default: VlmClassificationStrategy.MultiZone

max_concurrency

@property
def max_concurrency(self) -> int

@max_concurrency.setter
def max_concurrency(self, value: int) -> None

Maximum number of concurrent VLM API calls.

Type: int

Default: 1

max_tokens

@property
def max_tokens(self) -> int

@max_tokens.setter
def max_tokens(self, value: int) -> None

Maximum tokens in response (-1 = unlimited)

Type: int

Default: -1

model

@property
def model(self) -> str

@model.setter
def model(self, value: str) -> None

Model identifier to use.

Type: str

Default: "qwen/qwen3-vl-8b"

send_full_page_reference

@property
def send_full_page_reference(self) -> bool

@send_full_page_reference.setter
def send_full_page_reference(self, value: bool) -> None

Whether to send the full page image as reference context alongside cropped zones. Only used when UseZoneCropping is true.

Type: bool

Default: false

stream

@property
def stream(self) -> bool

@stream.setter
def stream(self, value: bool) -> None

Whether to stream responses from the API

Type: bool

Default: false

system_prompt

@property
def system_prompt(self) -> str

@system_prompt.setter
def system_prompt(self, value: str) -> None

Optional custom system prompt for zone classification. When empty, the module uses a default prompt based on the ClassificationStrategy.

Type: str

Default: string.Empty

temperature

@property
def temperature(self) -> float

@temperature.setter
def temperature(self, value: float) -> None

Temperature for response generation (0.0 = deterministic, 1.0 = creative). Defaults to 0.0 because zone classification and verbatim text extraction are deterministic tasks — randomness only adds run-to-run noise.

Type: float

Default: 0.0