> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/document-ai/cookbooks/choosing-a-model.md).

# Choosing a model

**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` |                 |

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

Omit it and you get `gemini-3`.

{% hint style="info" %}
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.
{% endhint %}

### 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](/document-ai/cookbooks/classify-then-extract.md) |
| 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.

```bash
#!/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=…
```

{% hint style="warning" %}
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.
{% endhint %}

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](/document-ai/guides-1/test-dashboard.md). Its test-execution endpoints are not part of the published API.

### Related pages

* [Extraction API](/document-ai/developer-documentation/integration-guides/extraction.md) — `model` alongside every other parameter.
* [Test Dashboard](/document-ai/guides-1/test-dashboard.md) — model comparison in the UI.
* [Quickstart](/document-ai/developer-documentation/getting-started/quickstart-extract-a-document.md) — where `extractionMetrics` is introduced.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.uptiq.ai/document-ai/cookbooks/choosing-a-model.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.