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. The client checks the size first and raises FileTooLargeError rather than sending the bytes to be refused.

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

The gap between polls grows from interval up to max_interval, so an hour-long transcription costs tens of requests, not hundreds.

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

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

Cancelling

A running job can be stopped, and the API refunds the credits it did not consume. Each job type has its own route, and the client knows which verb each one needs:

api.translation.cancel(file_uuid)  # also .resume(file_uuid)
api.transcription.cancel(job_id)
api.ocr.cancel(job_id)

Translation addresses files by UUID; conversion and summarization use the numeric job id the API returns. Passing the wrong shape is rejected by the API before it reaches the handler.

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

Retries

Transient failures are retried automatically with exponential backoff:

• 429 is always retried, on any method, honouring Retry-After — the request was refused before it ran, so nothing happened.
• 5xx and connection failures are retried only for GET, HEAD, PUT and DELETE. A POST that timed out may already have created a job, and jobs cost credits.
• Uploads are never retried: the file handle is consumed by the first attempt and cannot be replayed.

from forgefile import ForgeFile, RetryPolicy

ForgeFile(retries=RetryPolicy(attempts=5, backoff=1.0))
ForgeFile(retries=RetryPolicy(attempts=1))  # off

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.