Python Documentation

The sapling-py package provides a Python wrapper around the Sapling HTTP API. Install or upgrade to the latest release with pip:

python -m pip install --upgrade sapling-py

Or add it to a uv project:

uv add sapling-py

The core methods below require sapling-py 4.1.0 or newer. Additional methods and batch examples on this page require version 4.11.0 or newer.

Language API methods

from sapling import SaplingClient

client = SaplingClient(api_key="<api-key>")

rephrases = client.rephrase(
    "This is an example sentence.",
    mapping="paraphrase",
    num_results=3,
)
summary = client.summarize("A longer document to summarize...")
tones = client.tone("Thank you for resolving this so quickly!")
sentiment = client.sentiment("The support experience was excellent.")
quality = client.quality("Text to score for writing quality.")
language = client.langdetect("Bonjour tout le monde.")
profanity = client.profanity("Text to check.")

The client methods correspond to these API endpoints:

Client method	API documentation
rephrase()	Rephrase
summarize()	Summarize
tone()	Tone
sentiment()	Sentiment
quality()	Quality Score
langdetect()	Language Detection
profanity()	Profanity Detection

See each endpoint page for input limits, optional parameters, and response formats.

Additional client methods (4.11.0+)

The Python client also wraps classification, structured extraction, translation, content safety, AI detection, simplification, PII detection, and SEO analysis. Install sapling-py 4.11.0 or newer to use these methods.

from sapling import SaplingClient

client = SaplingClient(api_key="<api-key>")

classification = client.classify(
    "I was charged twice.", labels=["billing", "technical", "other"]
)
extraction = client.extract(
    "Invoice INV-1042 is due March 5, 2026.",
    fields=["invoice_number", {"name": "due_date", "type": "date"}],
)
translation = client.translate("Hello!", target_lang="fr")
safety = client.safety("Text to assess.", spans=True)
simplified = client.simplify(
    "The party shall remit payment upon receipt of the invoice.",
    reading_level="plain", preserve_terms=["invoice"],
)
detector = client.aidetect("Text to check for AI-generated content.")

Client method	API reference
classify()	Classification
extract()	Extraction
translate()	Translation
safety()	Content Safety
simplify()	Simplification
aidetect()	AI Detector
pii()	PII Detection
seo()	SEO Analysis

Batch requests

In version 4.11.0, classify(), extract(), safety(), langdetect(), translate(), summarize(), quality(), and aidetect() accept a list or tuple of 1–10 strings instead of a single string. The client sends the API's texts parameter; options such as labels or target language apply to all items. The result contains a results array in input order, with one single-input response per item. Each endpoint's combined character limit still applies.

languages = client.langdetect(["Bonjour le monde.", "Hello world."])
print([item["lang"] for item in languages["results"]])

translations = client.translate(
    ["Hello!", "Thank you."], target_lang="fr"
)
print([item["translation"] for item in translations["results"]])

Other methods, including simplify(), take one text string. Consult the individual endpoint references for input and billing limits.

Error handling

sapling-py raises SaplingError when the API returns a non-successful HTTP status. The exception exposes both the status code and raw response body:

from sapling import SaplingClient, SaplingError

client = SaplingClient(api_key="<api-key>")

try:
    result = client.summarize("Text to summarize.")
except SaplingError as error:
    print(error.status_code)
    print(error.body)

Network and timeout failures continue to use the exceptions raised by the underlying requests library.

Complete SaplingClient reference documentation is available on Read the Docs.