Doc Ai

Document AI — Sarvam Vision

Live in-chat document work → sarvam-mcp (sarvam_tools_vision_parse / _extract / _classify / _split). This skill = SDK code.

Translating a document into another language? → translate/document — a different API (client.document_translation.*), not this one.

SDK floor for the code below: Python sarvamai>=0.1.40, JS sarvamai@>=1.1.13. Older versions have doc_ai.digitise() instead of parse() and no classify()/split().

[!IMPORTANT] Auth: api-subscription-key header — NOT Authorization: Bearer. Base URL: https://api.sarvam.ai (NOT /v1 — that prefix is only for the OpenAI-compatible chat endpoint)

What this API does

Sarvam Vision is a 3B-parameter document-intelligence model, exposed through the Document AI API (SDK group: doc_ai / docAi). Four job types share one lifecycle (create → poll → fetch):

Parse and Extract fetch output with get_download_url / get_results; Classify and Split use a different call shape (a JSON request object, see below) and fetch with get_results.

Supports PDF, PNG, JPG, and ZIP (flat archive of page images) across 23 languages (22 Indian + English).

Quick Start — Parse (Python)

pythonCopy code
import os, time
from sarvamai import SarvamAI

client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])

# `file` is a list of (filename, fileobj, content_type) tuples — even for one document
with open("document.pdf", "rb") as f:
    job = client.doc_ai.parse(
        file=[("document.pdf", f, "application/pdf")],
        language="hi-IN",
        # `parse()` has no output_format kwarg (output is HTML by default) — send it as a raw form field:
        request_options={"additional_body_parameters": {"output_format": "md"}},   # "html", "md", or "json"
    )

TERMINAL = {"completed", "partially_completed", "failed", "rejected"}
while True:
    st = client.doc_ai.get_status(job_id=job.job_id)
    if st.status.lower() in TERMINAL:
        break
    time.sleep(5)

dl = client.doc_ai.get_download_url(job_id=job.job_id)
print("download:", dl.method, dl.url)   # a ZIP: primary file + per-page metadata JSON

Quick Start — Parse (JavaScript/TypeScript)

typescriptCopy code
import fs from "fs";
import { SarvamAIClient } from "sarvamai";

const client = new SarvamAIClient({ apiSubscriptionKey: process.env.SARVAM_API_KEY });

// `file` is an array, even for one document
// `parse()` has no output_format option in JS — output is HTML. For md/json, POST /doc-ai/v1/job/parse
// directly with an `output_format` form field.
const job = await client.docAi.parse({
  file: [fs.createReadStream("document.pdf")],
  language: "hi-IN",
});

const TERMINAL = new Set(["completed", "partially_completed", "failed", "rejected"]);
let st;
while (true) {
  st = await client.docAi.getStatus(job.job_id);   // positional — NOT { job_id }
  if (TERMINAL.has(st.status.toLowerCase())) break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

const dl = await client.docAi.getDownloadUrl(job.job_id);   // also positional
console.log("download:", dl.method, dl.url);

Extract (schema-based fields)

Same lifecycle, but pass a schema (or a saved config_id) alongside the file:

pythonCopy code
import json
schema = {
    "type": "object",
    "properties": {
        "policy_number": {"type": "string", "description": "Insurance policy number"},
        "sum_insured":   {"type": "number", "description": "Total sum insured, in INR"},
    },
}

with open("insurance-policy.pdf", "rb") as f:
    job = client.doc_ai.extract(
        file=[("insurance-policy.pdf", f, "application/pdf")],
        schema=json.dumps(schema),   # JSON string, not a dict — or pass config_id="cfg_abc123" instead
        language="en-IN",
        output_format="json",
    )
# ... poll get_status() same as above, then:
results = client.doc_ai.get_results(job_id=job.job_id)
print(results.result)   # {"policy_number": ..., "sum_insured": ...}

Classify and Split

Both take the file(s) plus a required request object that holds the options. They return an acceptance object (status="accepted"), then you poll and fetch get_results.

pythonCopy code
cats = [
    {"type": "invoice", "description": "A supplier bill with totals and payment details."},
    {"type": "bank_statement", "description": "A bank account statement."},
]

# Classify — scope "document" (default) gives one label; "page" gives one per page
with open("bundle.pdf", "rb") as f:
    job = client.doc_ai.classify(
        file=[("bundle.pdf", f, "application/pdf")],
        request={"config": {"scope": "page", "categories": cats}},
    )

# Split — methods: "semantic" (default), "fixed_pages", "page_ranges", "triggers"
with open("bundle.pdf", "rb") as f:
    job = client.doc_ai.split(
        file=[("bundle.pdf", f, "application/pdf")],
        request={"config": {"method": "semantic", "classify_segments": True, "categories": cats}},
    )

# ... poll get_status() as above, then:
r = client.doc_ai.get_results(job_id=job.job_id)          # include="details" adds pages/evidence
for seg in r.result.segments:                              # Split
    print(seg.pages, seg.type, seg.review_required)
# Classify: r.result.type (scope "document") or r.result.decisions[i].type / .input_page (scope "page")

typescriptCopy code
const job = await client.docAi.split({
  file: [fs.createReadStream("bundle.pdf")],
  request: { config: { method: "fixed_pages", pages_per_segment: 2, classify_segments: false } },
});
// ... poll getStatus(job.job_id), then:
const r: any = await client.docAi.getResults(job.job_id, { include: "details" });
console.log(r.result.segments.map((s: any) => [s.pages, s.type]));

Gotchas

Full Docs

Fetch schema rules, table-extraction details, and rate limits from:

• https://docs.sarvam.ai/llms.txt — comprehensive docs index
• Document AI Overview
• Sarvam Vision Model Page
• Rate Limits