forgefile-python

Python client for the ForgeFile REST API — translate, transcribe, convert, OCR, summarize and rewrite files.

Requires Python 3.11+.

Install

pip install forgefile

Quick start

from forgefile import ForgeFile

with ForgeFile("your-token") as api:
    job = api.jobs.translate("contract.pdf", target_language="es")
    api.files.wait(job.uuid)
    api.files.download(job.uuid, "contract.es.pdf")

The token is read from FORGEFILE_API_KEY when the first argument is omitted. Public endpoints need no token at all:

with ForgeFile() as api:
    for language in api.public.languages():
        print(language.code, language.name)

Processing a file

Every job endpoint uploads the file and starts the work in one call, returning a FileJob whose uuid identifies it from then on.

api.jobs.translate("contract.pdf", target_language="de")  # source_language is optional
api.jobs.transcribe("interview.mp3")
api.jobs.convert("report.docx", to_format="pdf")
api.jobs.ocr("receipt.jpg")
api.jobs.summarize("paper.pdf")
api.jobs.rewrite("draft.docx")
api.jobs.compress("scan.pdf")

Uploads are capped at 10 MB by the API.

Waiting for the result

wait() blocks until the job reaches a terminal state and raises JobTimeoutError if it does not. The job keeps running server-side, so calling again resumes waiting.

finished = api.files.wait(job.uuid, timeout=900, interval=5)

if finished.succeeded:
    transcript = api.files.result(job.uuid)  # structured output
    api.files.download(job.uuid, "interview.srt")

track() yields every observed state instead, for progress reporting:

for state in api.files.track(job.uuid, interval=5):
    print(state.status)

Branch on job.is_finished and job.succeeded rather than comparing status strings — a status this client does not recognise is never treated as finished, so a wait loop cannot end early on a state it has not seen.

Errors

Every failure raises a subclass of ForgeFileError carrying the API's stable error_code, so you can branch on the code rather than on message text.

from forgefile import RateLimitError, ValidationError

try:
    api.jobs.translate("contract.pdf", target_language="es")
except ValidationError as exc:
    print(exc.context)  # field errors
except RateLimitError as exc:
    print(f"retry in {exc.retry_after}s")

The API allows 60 requests per minute.

Configuration

Examples

Runnable scripts in examples/:

Architecture

Resources depend on the HTTPTransport protocol, never on httpx, so the HTTP layer can be replaced with a recorded fixture, a proxy or a different library — see examples/06_custom_transport.py.

Response models accept unknown fields, which stay reachable through model_extra. Only fields observed against the live API are typed explicitly; authenticated endpoints could not be inspected without a token while this client was written, so their payloads are permissive rather than guessed.

The package ships a py.typed marker, so your type checker sees these signatures.

Development

git clone https://github.com/ForgeFile/forgefile-python
cd forgefile-python
uv sync

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest

Tests make no network calls: the resource layer runs against a fake transport, the httpx layer against respx. CI runs these commands on Python 3.11, 3.12 and 3.13.

Links

• ForgeFile — the product
• API reference
• Source and issues
• ForgeFile on GitHub
• Support — support@forgefile.com

MIT licensed. See LICENSE.