Realtime TTS-2 is live. Built for realtime conversation that feels human. Read the Realtime TTS-2 announcement

Extractions

Pull typed fields (text, numbers, dates, lists, estimates) out of text or images, such as an invoice number, total and due date from a scanned receipt, with a confidence for each value

Preview. The /alpha path and the request and response shape may change before this API is marked stable. See release stages.

The Extractions API runs an extraction model that reads text or images and returns the values you ask for as typed fields. You send a state (the content to read), optional images in assets, and a map of named fields, each with a type such as text, number or date. You get back one answer per field: the value, how confident the model is, and how likely the value is to be missing from the input.

Use it to turn documents into data: invoice and receipt fields, form entries, dates and amounts in emails, line items, or a number the content implies but doesn't state. Requests use your Inworld API key and are billed to your Inworld account.

EndpointPOST https://api.inworld.ai/alpha/extractions
ModelsCall the List models API with output_modalities=extractions
InputText, and PNG, JPEG or WebP images. PDFs are not accepted; see PDFs
StreamingNot supported: every answer comes back in one response
PricingInput tokens only; see Billing
Rate limitPer account, the same requests per second as chat completions on your plan; see Rate limits

Choose an API

Extractions, Decisions and structured outputs on chat completions all return machine-readable results. Choose by what your code needs back:

UseWhen you needYou get
Extractions (/alpha/extractions)Values read from text or images: names, IDs, amounts, dates, lists, or an estimate of a numberOne typed value per field, with confidence and the probability that the value is absent (p_null). Billed on input tokens only
Decisions (/alpha/decisions)A judgment about the content: yes or no, one of your options, or a scoreA probability, one of your options, or a level on your scale
Structured outputs (/v1/chat/completions)JSON in your own schema, with nested objects or generated text, or a PDF as inputJSON generated by a chat model, which you validate yourself. Billed on input and output tokens

To read a document and then decide what to do with it, you can call Extractions for the values and Decisions for the judgment.

Choose a model

Call the List models API with ?output_modalities=extractions to list extraction models. Extraction models are not in the default listing. Each model's endpoints is ["/alpha/extractions"], spec.inputModalities shows whether it reads images (image), and spec.contextLength is how many tokens of input it reads. A chat model or a decision model can't be used on this endpoint.

The examples on this page use inworld/models/clairic, which reads text and images. Send a model's id from List models unchanged. The response's model names the model that answered and can be a shorter form of that id, such as inworld/clairic.

Extract fields from text

Run these examples on your server. Set INWORLD_API_KEY to the Base64 credentials copied from Portal or the CLI; see authentication.

bash
curl -X POST https://api.inworld.ai/alpha/extractions \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "inworld/models/clairic",
    "state": "Invoice INV-20417 from Example Supply Co. Issued October 28, 2026. Payment terms: net 30. Total due: $712.26.",
    "fields": {
      "invoice_number": {"type": "text", "instructions": "The invoice number"},
      "total": {"type": "number", "instructions": "The total amount due", "unit": "USD", "decimals": 2},
      "due_date": {"type": "date", "instructions": "When payment is due"}
    }
  }'

Response:

json
{
  "model": "inworld/clairic",
  "answers": {
    "invoice_number": {
      "type": "text",
      "value": "INV-20417",
      "guess": "INV-20417",
      "confidence": 1,
      "p_null": 0.00005,
      "span": [8, 17]
    },
    "total": {
      "type": "number",
      "value": 712.26,
      "guess": 712.26,
      "confidence": 0.99999,
      "p_null": 0.00000002
    },
    "due_date": {
      "type": "date",
      "value": "2026-11-27",
      "guess": "2026-11-27",
      "confidence": 0.99994,
      "p_null": 0.0000026
    }
  },
  "truncated": false,
  "usage": {
    "state_tokens": 45,
    "image_tokens": 0,
    "schema_tokens": 272,
    "input_tokens": 362,
    "output_tokens": 0,
    "passes": 2
  },
  "metadata": {
    "attempts": [
      { "model": "inworld/clairic", "status_code": 200, "duration_ms": 209.9, "success": true }
    ],
    "generation_id": "41149c81-1125-4eb4-89a7-eb76c429af4a",
    "total_duration_ms": 210
  }
}

The text doesn't state a due date, so the model computed it from the issue date and the payment terms. To resolve relative dates such as "yesterday" or "next Friday", set reference_date (YYYY-MM-DD) to the date the content was written.

Extract fields from an image

Send each image in assets under a key you choose, and write that key in state (or in a field's instructions) where the image belongs. An asset whose key appears nowhere returns 400.

Invoice from Example Supply Co.: invoice number INV-20417, due date November 27, 2026, total due $712.26

Save the invoice above as invoice.png. In the same directory, install the Python dependency and set your API key:

bash
python -m pip install requests
export INWORLD_API_KEY="<your Base64 API key>"

Save the following as extract_invoice.py:

python
import base64
import os
from pathlib import Path

import requests

image = base64.b64encode(Path("invoice.png").read_bytes()).decode("ascii")
response = requests.post(
    "https://api.inworld.ai/alpha/extractions",
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "model": "inworld/models/clairic",
        "state": "The supplier's invoice: invoice_scan",
        "assets": {"invoice_scan": {"format": "png", "data_base64": image}},
        "fields": {
            "invoice_number": {"type": "text", "instructions": "The invoice number"},
            "total": {
                "type": "number",
                "instructions": "The total amount due",
                "unit": "USD",
                "decimals": 2,
            },
            "due_date": {"type": "date", "instructions": "When payment is due"},
        },
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
if result["truncated"]:
    print("The input was cut to fit the model's context; check the answers.")
for name, answer in result["answers"].items():
    print(name, answer["value"], f"confidence={answer['confidence']:.2f}")

Run it from the directory containing both files:

bash
python extract_invoice.py

It prints each field with its value and confidence:

text
due_date 2026-11-27 confidence=1.00
invoice_number INV-20417 confidence=1.00
total 712.26 confidence=1.00

An asset is {"format": "png", "data_base64": "..."}. format is png, jpg, jpeg or webp, and data_base64 is standard base64 with no data: prefix. The key must stand alone in the text: invoice_scan matches in "invoice: invoice_scan" but not in "invoice_scan_2". When state would only name the image, it can be an empty string and the key can go in a field's instructions instead. An answer the model read from an image carries "source": "image", and a text answer read from an image has no character position (span is null).

PDFs and multi-page documents

The Extractions API reads images, not PDFs: an asset with format: pdf returns 400. For a PDF, either:

  • Render each page to PNG or JPEG and send the pages as assets. The example model reads up to four images per request, and a request carrying images must fit in 4 MiB. For longer documents, send a few pages per request.
  • Send the PDF to a chat model that accepts files and ask for structured outputs. See PDF input.

Field types

Each entry in fields is keyed by a name you choose, and its answer comes back under the same name. Every field has a type; instructions tells the model what to look for. Write instructions as you would label the field on a form.

typeExtractsvalue
textA string from the content, such as a name or an IDA string
numberA number. Optional unit, decimals (0 to 6) and integerA number
date, time, datetimeA calendar date, a time of day, or bothISO 8601: 2026-11-27, 09:30:00, 2026-11-03T09:30:00
durationA length of time, in your unitA number
listEvery matching item. Requires items: text, number or dateAn array
estimateA number or date the content implies but may not state, within min and max (both required, both numbers or both YYYY-MM-DD dates)The expected value, plus median, p10 and p90
forecastThe next values of a series. Requires min, max, horizon (1 to 64 steps) and interval (such as month)An array with one expected value per step, plus median, p10 and p90 arrays

See Create extraction for every field option and answer member.

Use the answers in your application

For text, number, date, time, datetime and duration fields, each answer has:

  • value: the extracted value, or null when the model judges it absent from the input.
  • guess: the model's best candidate, even when value is null.
  • confidence: from 0 to 1, how sure the model is of guess.
  • p_null: from 0 to 1, the probability that the input doesn't contain the field. Set a field's null_threshold (0 to 1) to control when value becomes null.
  • span: for text, the start and end character positions of the value in state, end exclusive.

A list answer has value (an array), confidence and, for text read from state, spans. An estimate answer's value is the expected value; set options.include_quantiles to true to also get the full quantiles array.

Before you store a value, check it in your code: send low-confidence answers and null values for review instead of trusting them. Choose the threshold from examples of your own documents. Also check truncated: when it is true, the input was longer than the model's context and was cut, so a field near the end may be missing or guessed. Split long documents into several requests.

The response's model is the model you requested. metadata reports attempts, generation_id and total_duration_ms.

Limits

LimitValue
Request body16 MiB. A request that carries images must fit in 4 MiB, including the base64 encoding
Images per requestUp to 4 for inworld/models/clairic; other models can differ. More images than the model reads returns 400
Input lengthThe model's spec.contextLength in tokens. Longer input is cut and the response has truncated: true
Timeout60 seconds
Zero data retentionNot available for workspaces with zero data retention when the model can't serve them: the request returns 400

Resize or compress images before you send them: base64 encoding makes each image about a third larger in the request.

Errors

Check the HTTP status and the response content type before parsing the body. Extractions errors use {"error": {"message": "...", "type": "..."}}. Request validation returns 400 before the request reaches a model, with error.param naming the field to fix, such as fields.total.type or assets.invoice_scan.format. Branch on the status, error.type and error.param, not on error.message: messages are for people and can change while the API is in Preview. Errors for authentication, credits and your account's rate limit use a different body: 401 and 429 are plain text, and 402 has a numeric error.code.

Statuserror.typeMeaningWhat to do
400invalid_request_errorInvalid request: a missing state or fields, an unknown field type, a missing required field option, an invalid reference_date, an asset that is a PDF, has an unsupported format, has a data: prefix or isn't referenced, more images than the model reads, an unknown model, or a decision model. Also returned for workspaces with zero data retention when the model can't serve themFix the request as the error describes. For zero data retention, use a workspace without it
401Missing or invalid Inworld API keyCheck the Authorization header
402Your account has no credits remainingAdd credits, then retry
404not_found_errorThe model was retiredChoose another extraction model
413invalid_request_error, or a body with a numeric code over 16 MiBThe body is over 4 MiB with images, or over 16 MiBSend smaller or fewer images, or less state
422invalid_request_errorThe model rejected input that passed request validationFix the request as the error describes
429rate_limit_errorYour account's request limit (plain-text body), or the model is rate limitedRetry with exponential backoff and jitter; honor Retry-After when present
500, 502api_error, upstream_errorThe model could not be reached or failed to answerRetry with exponential backoff
503api_errorAt capacity, or model is not an extraction model ("this model is not available on the extractions API")Check that the model is listed with output_modalities=extractions; otherwise retry with exponential backoff and honor Retry-After
504timeout_errorNo answer within 60 secondsRetry, or send less input per request

Billing

Extractions are billed on input tokens only, the response's usage.input_tokens. Output is not billed, and requests that return an error are not billed. input_tokens includes the state, the images and your field definitions, and can be larger than state_tokens + image_tokens + schema_tokens, because the model can read the input more than once (usage.passes). Field definitions count on every request, so short instructions cost less.

For the model's current rate per input token, read pricing.promptToken in the List models API response.