Extraction

Use Extraction to turn text, images, and PDFs into JSON shaped by a schema you define. It fits invoices, receipts, forms, contracts, and other documents where your application needs the same fields from every document, such as a number, a company name, a total, or a list of line items.

Before calling this endpoint, create an API key and make sure the account has a positive balance.

Extraction, Fetch, or Media Descriptions #

These three services read documents, but they return different things:

Choose Extraction when you already know which fields you need and want them read directly from the document. Choose Fetch when you need the document’s full text, for example to index it or to read a web page. Choose Media Descriptions when you need an explanation of visual or audiovisual content, such as a chart, a photo, or a video, rather than specific fields.

Endpoint #

Build the request #

Each property in responseSchema is one field to find. Its description is the search criterion, so write it as a short, specific definition, such as “total amount due” instead of “total”. Nested objects and arrays of objects are supported. $ref and $defs are not; inline every definition instead.

Images and files accept base64 data URLs or public HTTP(S) URLs:

• Supported formats are JPEG, PNG, TIFF, and PDF, including multi-page PDFs.
• AIVAX downloads remote URLs before processing, within the file size limit in Pricing and limits. The resource must be reachable without sign-in.
• Other content types, such as audio or video, return 400 Bad Request. The error does not identify which document was rejected, so check the content type of each document in the request.

The following request extracts invoice fields from a text document and a PDF:

{
  "instructions": "Only consider the issuing company as the vendor.",
  "responseSchema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string", "description": "invoice number" },
      "vendor": { "type": "string", "description": "company that issued the invoice" },
      "total": { "type": "number", "description": "total amount due" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "product": { "type": "string", "description": "product name" },
            "quantity": { "type": "integer", "description": "number of units" }
          }
        }
      }
    }
  },
  "documents": [
    {
      "type": "text",
      "text": "Invoice 1042 from Acme Corp. 2 x Widget at $10.00. Total: 20.00 USD."
    },
    {
      "type": "file",
      "file": {
        "filename": "invoice.pdf",
        "file_data": "https://example.com/invoice.pdf"
      }
    }
  ]
}

Read the response #

data contains one object per document, in the same order as documents. Each object uses the property names from your schema. Values are converted to the number, integer, or boolean type declared in the schema when possible. A field that is not found is null, and an array with no matches is empty.

{
  "message": null,
  "data": [
    {
      "invoice_number": "1042",
      "vendor": "Acme Corp",
      "total": 20,
      "line_items": [
        { "product": "Widget", "quantity": 2 }
      ]
    }
  ]
}

Documents are processed independently and in parallel. If any document fails, the whole request returns an error instead of partial results. Correct or remove that document and retry. Documents that finished before the failure are still billed and count toward your quota, so retry only after fixing the failing document.

Extracted values are model-generated. They can be missing, incomplete, or wrong, especially in low-quality scans or complex layouts. Validate the structure and verify consequential values, such as amounts and identifiers, against the original document.

Pricing and limits #

Extraction is billed for the input tokens of each document. Output tokens are not billed.

Extraction and Summarization share the same document limits. Remote files are downloaded up to 5 MB each. The number of processed documents per minute and per day depends on the plan; see Data processing limits.

The quota counts every item in the request’s documents array, not each HTTP request. A request that would exceed any active window returns 429 Too Many Requests.

The embedded API reference contains the server-maintained request, response, authentication, and error details: