Choosing a model

Pick between the five models, and know when it matters.

Goal. Understand the model parameter, when changing it is worth doing, and how to compare options on your own documents rather than on someone else's benchmark.

The available models

model accepts five values, on extraction and classification alike:

Value
gemini-3	The default
gpt-4.1
gpt-5.1
openrouter/z-ai/glm-5.2
openrouter/deepseek/deepseek-v4-pro

{
  "documentType": "BalanceSheet",
  "content": "…",
  "model": "gpt-5.1"
}

Omit it and you get gemini-3.

The portal's model picker additionally offers Default model as a distinct choice from naming gemini-3 explicitly. Over the API there is no such distinction — omitting model and sending "gemini-3" are the same request. Pin the value explicitly if you want your results to stay comparable across a future change of default.

When to change it

Usually: do not. The default is the default for a reason, and model choice is rarely the reason an extraction is disappointing. Work through the cheaper explanations first.

Symptom	Look at before changing model
Fields missing	documentType correct? Check extractionMetrics.missingFields
Poor accuracy on scans	documentQuality.level and sharpness — a bad scan defeats any model
Wrong fields entirely	Classification — see Classify, then extract
Inconsistent run to run	enableCaching, and whether the prompt varies

Model choice is worth testing when a specific document type consistently underperforms, when you have a latency or cost target the default misses, or when your documents have an unusual language or layout profile.

Comparing models on your own documents

There is no benchmarking endpoint in the published API, so run the comparison yourself against documents that look like yours. extractionMetrics gives you the scoring.

#!/usr/bin/env bash
# Compare models on one document. Extraction is ~90s per run — this is slow.
set -euo pipefail

DOC=$1
TYPE=$2
MODELS="gemini-3 gpt-4.1 gpt-5.1"

for MODEL in $MODELS; do
  python -c "
import base64, json, sys
json.dump({
  'documentType': sys.argv[1],
  'model': sys.argv[2],
  'content': base64.b64encode(open(sys.argv[3],'rb').read()).decode()
}, open('req.json','w'))
" "$TYPE" "$MODEL" "$DOC"

  curl -s -X POST "https://api-docai-uat.uptiq.ai/extract/sync" \
    -H "X-Api-Key: $DOCAI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @req.json -o "result-$MODEL.json"

  jq -r --arg m "$MODEL" '
    .result as $r |
    "\($m)\taccuracy=\($r.extractionMetrics.accuracyScore)" +
    "\tcomplete=\($r.extractionMetrics.completenessScore)" +
    "\ttokens=\($r.tokenUsage.total_tokens)" +
    "\tsecs=\($r.extraction_time_seconds)"' "result-$MODEL.json"
done

Which produces something you can actually decide on:

gemini-3   accuracy=85.67  complete=66.67  tokens=29375  secs=90.8
gpt-4.1    accuracy=…      complete=…      tokens=…      secs=…
gpt-5.1    accuracy=…      complete=…      tokens=…      secs=…

Set enableCaching: false and overrideCache: true when comparing, or a cached result from an earlier run will be returned and every model will look identical.

Run each model over a set of representative documents, not one. A single document tells you about that document.

What to weigh

Signal	Where
Accuracy	result.extractionMetrics.accuracyScore
Completeness	result.extractionMetrics.completenessScore and missingFields
Rule compliance	rulesPassed / rulesChecked
Latency	result.extraction_time_seconds
Token cost	result.tokenUsage.total_tokens
Credit cost	creditReservation.cost on the async record

Cost and accuracy usually trade off. The right answer depends on whether a missed field costs you a human review or a bad lending decision.

Related parameters worth trying first

Several parameters affect quality more cheaply than a model swap:

Parameter	Effect
enableJudge	A second model reviews the extraction afterwards. Higher confidence, more cost
extractionPrompt	Natural-language guidance for this document type
agentInstructions	System-level instructions injected into the prompt
analysisDepth	standard does full analysis; quick skips classification when the type is known
quickExtract	Native PDF extraction, bypassing OCR — faster, potentially less accurate
extractionFormat	Your own JSON schema for the output structure

extractionPrompt and agentInstructions are often the higher-leverage change when a specific field is being missed.

Doing this in the portal

The Test Dashboard runs test cases against document types and reports accuracy per model, including a comparison matrix. If you are evaluating rather than automating, start there — see Test Dashboard. Its test-execution endpoints are not part of the published API.

Related pages

• Extraction API — model alongside every other parameter.

• Test Dashboard — model comparison in the UI.

• Quickstart — where extractionMetrics is introduced.