How do you build document processing with an OpenAI-compatible API?

Key facts

Endpoint	POST https://api.plugsky.com/v1/chat/completions with JSON mode for classification and extraction
Compatibility	Same shape as OpenAI; change base_url and model name
Parsing	Text extraction and OCR run in your infrastructure; the files endpoint is coming soon
Models	30+ models; cheap aliases for routing and stronger ones for difficult extraction
Pricing model	Flat monthly self-serve plans with unlimited fair-use usage
Free tier	Free plan with 2 free AI models, no card required
Throughput	Queue with bounded concurrency and idempotency; the batch endpoint is coming soon
Governance	Scoped keys and per-document audit logs

TL;DR

• Classify first with a fixed enum, then apply the schema for that document type.
• Validate in code; JSON mode gives shape, not truth.
• Keep the document hash as the idempotency key for every downstream write.
• Use cheap aliases for routing and summaries, stronger ones for hard extraction.
• Files and batch endpoints are coming soon — own parsing and queueing today.

How it works, step by step

1. Change the base URL to Plugsky and confirm an existing structured-output request parses unchanged.
2. Register documents with a content hash and route by classification into a fixed enum of types.
3. Parse text and structure in your pipeline, then call JSON mode with the matching extraction schema.
4. Summarize long documents for review queues and notifications with a separate, cheap call.
5. Validate fields and summaries against rules; retry once, then flag for human review.
6. Write results idempotently and store a per-document trace of stages, model versions and outcomes.

Original data

Try it yourself

Open the API migration checker →

Architecture of an API-first document workflow

The API handles language tasks; the pipeline handles everything else:

• Ingest and parse: your collectors fetch documents, extract text and run OCR where needed.
• Classify: a JSON-mode call returns document type and confidence from a fixed enum.
• Extract: the schema for that type produces structured fields, including explicit nulls.
• Summarize: a short, cheap call produces a routing summary for human queues.
• Validate and deliver: schema and business rules, then idempotent writes with a document trace.

Implementation details

Practical rules for document workflows:

• Keep classification labels closed-ended; adding an unknown option is better than forcing a wrong type.
• Send only the text needed for the current stage — classification rarely needs the whole document.
• Use the content hash as an idempotency key for all downstream writes, so retries and replays are safe.
• Version schemas and store the version with each result; documents processed last quarter must remain interpretable.
• Cap output tokens per stage so a summary cannot consume a document-sized budget.
• Separate queues per document family so one slow type cannot starve the rest.

Evaluation and limitations

Measure the workflow end to end and per stage:

• Classification accuracy: confusion between similar document types is the most common upstream error.
• Per-field extraction accuracy: exact match for formatted values and normalized comparison for text.
• Straight-through processing: documents completed without human intervention.
• Exception rate: validation failures and review-queue volume per thousand documents.
• Summary usefulness: reviewer feedback on routing summaries, kept short and specific.

Honest limits: parsing and OCR are yours until the files endpoint ships, batch processing is coming soon, table-heavy documents often need specialized extraction, and sensitive documents require a PII policy that applies before any model call.

Honest comparison

Capability	Document workflow on Plugsky	Managed IDP platform	Rules-based processing
Classification	JSON mode with a closed enum	Vendor models	Keyword rules
Extraction	Your schemas, any field set	Prebuilt document types	Template-based
Model choice	30+ aliases across stages	Vendor-selected	None
Integration	OpenAI-compatible calls in your stack	Platform SDK	Custom code
Cost shape	Flat monthly self-serve, unlimited fair use	Per-document pricing	Engineering time

Frequently asked questions

Does Plugsky parse documents for me?

Not yet — the files endpoint is coming soon. Text extraction and OCR run in your infrastructure; Plugsky handles classification, extraction and summarization from the text you provide.

How do I classify documents reliably?

Use a closed enum in JSON mode with a confidence value and an unknown option, and validate classification accuracy on a labeled sample before automating routing.

How do I keep bulk processing safe?

Queue work with bounded concurrency, use the document hash as an idempotency key, retry transient errors with backoff and store failures for reprocessing.

Which stages should use cheap models?

Classification, routing and summaries run well on plugsky-micro or plugsky-lite. Reserve stronger aliases for difficult extraction from legal, financial or technical documents.

Can summaries be trusted for routing?

Treat them as navigation aids for humans, not as validated facts. Generate them separately from extraction and keep them short.

What about sensitive documents?

Apply your PII policy before any model call, redact what the model does not need, and align logs and retention with the regions you serve.

Can I build the pipeline on the free plan?

Yes. The free plan includes two free models with no card, and the 14-day full-access trial supports evaluation with paid aliases on real document samples.