Structured extraction

POST /v1/extract turns text, images, or PDFs into JSON that matches your schema — guaranteed. Send a JSON Schema and a source; the gateway reads the document (OCR for PDFs and images), runs a structured-output model, validates the result against your schema server-side, and silently retries with the errors fed back if it doesn't conform. You only ever receive data that fits, or an honest 422. No prompt engineering, no validation loop, no glue code.

curl https://api.gopuram.net/v1/extract \
  -H "Authorization: Bearer $GOPURAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"},
        "due_date": {"type": "string"}
      },
      "required": ["invoice_number", "total"]
    },
    "input": {"type": "document_url", "document_url": "data:application/pdf;base64,<PDF>"}
  }'

{
  "object": "extraction",
  "model": "google/gemini-3.6-flash",
  "data": { "invoice_number": "4217", "total": 145.5, "due_date": "2026-09-30" },
  "usage": {
    "cost": 0.01347,
    "input_tokens": 2311,
    "output_tokens": 188,
    "steps": [
      { "kind": "ocr", "model": "mistral/mistral-ocr", "pages": 3, "cost": 0.0126 },
      { "kind": "llm", "model": "google/gemini-3.6-flash", "attempt": 1, "cost": 0.00087 }
    ]
  }
}

Request

What the gateway does for you

1. Documents become text: PDFs and images run through the dedicated OCR model first (billed per page, itemized in steps).
2. The model extracts: a structured-output chat call with your schema.
3. We validate — really validate: the output is checked against your schema with a full JSON Schema validator. On failure, the validator's errors are fed back to the model and it retries (up to 3 attempts total, each billed — they appear in steps).
4. You get a guarantee: data always conforms, or you get a 422 schema_validation_failed whose error.details carries the exact validator errors — and whose usage still itemizes what ran, because the work happened and honest billing is the house rule.

Cost transparency

usage.cost is the exact billed total; usage.steps breaks it down per step at each model's normal catalog price. Multi-step work, one receipt, in-band — no second metering call, no month-end surprise.

Recipes

• Invoices/receipts — the example above; add instructions for currency normalization.
• Résumé parsing — schema with name, roles[], skills[]; input as PDF data URL.
• Email → order — {type: "text"} input with the email body; schema for items, quantities, address.
• Photographed forms — {type: "image_url"} with a phone photo; OCR handles skew and handwriting surprisingly well.

Deeper OCR control (page ranges, table formats) lives on /v1/ocr; /v1/extract is the "just give me the JSON" path.