Self-Hosted DeploymentsAWS SageMakerAPI reference

API reference — Sarvam Vision

View as Markdown

The contract for invoking a self-hosted Sarvam Vision endpoint. You send the raw document bytes as the request body and pass options as custom attributes.

InvokeEndpoint

FieldValue
Operationsagemaker-runtime:InvokeEndpoint (sync) · InvokeEndpointAsync (async)
Request bodythe raw document bytes
Content-Typemust match the bytes (magic-byte verified) — see below
Acceptapplication/json (default) or application/zip (bundle)

Supported content types

Content-TypeFile type
application/pdfPDF
image/pngPNG image
image/jpeg (or image/jpg)JPEG image
application/zip (or application/x-zip-compressed)ZIP of images

An omitted type, application/octet-stream, or text/plain is treated as PDF and the bytes are sniffed. A Content-Type that doesn’t match the bytes is rejected with 400 INVALID_INPUT.

TIFF, WebP, BMP, and GIF are not supported — they’re rejected with 415 UNSUPPORTED_MEDIA_TYPE. Convert to PNG, JPEG, or PDF first.

Limits

LimitValueError if exceeded
File size (container hard cap)200 MB413 PAYLOAD_TOO_LARGE
File size (sync endpoint)~6 MB (AWS cap)AWS-side rejection before the container
File size (async endpoint)50 MBAWS-side / job failure
Pages per sync request5 (recommended)risk of the 60 s InvokeEndpoint timeout beyond this
Pages per document (hard cap)500413 PAYLOAD_TOO_LARGE

Options — custom attributes

Pass options in the X-Amzn-SageMaker-Custom-Attributes header (sync) or the CustomAttributes parameter (async), as key=value,key=value or a JSON object.

AttributeValuesDefaultNotes
languagehi-IN, en-IN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, or-IN, pa-IN, ta-IN, te-IN, ur-IN, as-IN, bodo-IN, doi-IN, ks-IN, kok-IN, mai-IN, mni-IN, ne-IN, sa-IN, sat-IN, sd-INhi-INcase-insensitive; anything else → 400 UNSUPPORTED_LANGUAGE
output_formatmd | html | jsonmdjson adds structured result.pages[]
outputtext | ziptextresponse representation (see below)
filenamee.g. invoice.pdfderived from Content-Typeappears in logs and results

Response

The default response is a JSON envelope (Content-Type: application/json):

1{
2  "schema_version": "1.0",
3  "status": "completed",
4  "job_id": "20260724_...",
5  "result": {
6    "format": "md",
7    "text": "…merged document text…",
8    "summary": { "total": 1, "succeeded": 1, "failed": 0 }
9  },
10  "warnings": []
11}

With output_format=json, result.pages[] is added — per page page_num, width, height, unit, origin, and blocks[] with id, type (layout tag), reading_order, bbox, text, layout_confidence, and ocr_confidence.

Set output=zip (or send Accept: application/zip) to get a zip bundle instead: the merged document at the root ({name}.md / .html, always present) plus metadata/page_NNN.json per page.

The response header X-Amzn-SageMaker-Custom-Attributes echoes job_id, schema_version, and api_version. Log the job_id — support can trace any request with it.

The sync endpoint is for small documents (up to 5 pages) at low concurrency. It must finish inside AWS’s 60-second timeout, so keep sync requests to 5 pages or fewer and, on the recommended single-GPU instance (ml.g6e.xlarge), only 1–2 documents in flight or requests will time out. For anything larger than 5 pages, higher concurrency, or bulk work, use an async endpoint or batch transform — see Deploy Sarvam Vision.

Errors

Every non-2xx is delivered as HTTP 424 through InvokeEndpoint — branch on OriginalStatusCode plus error.code / error.detail_code, never on the HTTP status. See Error handling on SageMaker for the collapse rule and the shared envelope.

Errors always come back as the same JSON envelope — never HTML, never a bare string. The error envelope uses schema_version: "2.0" (a successful response is "1.0" — a known inconsistency). error carries code (the class), detail_code (the specific reason), message, retryable, and request_id — plus retry_after on an overload 503:

1{
2  "schema_version": "2.0",
3  "status": "error",
4  "error": {
5    "code": "invalid_request_error",
6    "detail_code": "UNSUPPORTED_MEDIA_TYPE",
7    "message": "content type 'image/tiff' is not supported; supported: application/pdf, image/png, image/jpeg, application/zip …",
8    "retryable": false,
9    "request_id": "20260729_…"
10  }
11}

Client errors — fix the request, don’t retry

error.code is invalid_request_error and retryable is false; the error.detail_code names the specific reason.

OriginalStatusCodeerror.detail_codeMeaning
400INVALID_INPUTempty body, corrupt/truncated or password-protected PDF, bytes don’t match Content-Type, zero pages
400UNSUPPORTED_LANGUAGElanguage not in the list above (e.g. "unsupported language 'fr-FR'")
413PAYLOAD_TOO_LARGEover 200 MB or over 500 pages — split the document
415UNSUPPORTED_MEDIA_TYPETIFF/WebP/BMP/GIF or another unsupported type — convert to PDF/PNG/JPEG

Overload — back off and retry

error.code is service_overloaded, retryable is true, and the body carries retry_after (seconds). The container sheds immediately rather than queueing.

1{
2  "schema_version": "2.0",
3  "status": "error",
4  "error": {
5    "code": "service_overloaded",
6    "detail_code": "SERVICE_UNAVAILABLE",
7    "message": "server at capacity, retry later",
8    "retryable": true,
9    "request_id": "20260729_…",
10    "retry_after": 5
11  }
12}

Other server errors — retryable

retryable is true; back off and retry, and report error.request_id if one file fails persistently.

OriginalStatusCodeerror.detail_codeMeaning
500INTERNAL_ERRORprocessing failed (rare) — resubmit
503INSUFFICIENT_STORAGEinstance disk guard tripped — sustained → raise instance volume size
504PROCESSING_TIMEOUTdocument exceeded the per-job wait budget — raise timeouts (async) or split

Rule of thumb: 4xx = fix the request; 5xx = retry with backoff. The retryable flag in every error body encodes exactly this.

Deploy a Sarvam Vision endpoint

Step-by-step real-time, async, and batch deployment with boto3.