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

Extractions

Create extraction

Extract typed fields from text or images

POST/alpha/extractions

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

Send a state, optional images in assets, and a map of typed fields to the selected extraction model. It returns one answer per field: the value, the model's confidence, and the probability that the value is absent (p_null).

Find extraction models with the List models API and output_modalities=extractions. The Extractions guide explains when to use this API instead of Decisions or structured outputs, and shows a complete image request. The reference examples use inworld/models/clairic.

Images

Send each image in assets under a reference key, and write the key in state or in a field's instructions where the image belongs:

json
{
  "state": "The supplier's invoice: invoice_scan",
  "assets": {
    "invoice_scan": { "format": "png", "data_base64": "<BASE64_IMAGE>" }
  }
}

This fragment illustrates state and assets; a complete request also requires model and fields.

Field or constraintAccepted values and behavior
formatpng, jpg, jpeg or webp. pdf and type: document return 400: render PDF pages to images first.
data_base64Standard base64 of the image bytes, with no data: prefix.
Reference keyMust appear in state or in some field's instructions as a standalone token: a letter, digit, _, . or - directly before or after it makes it part of a longer word. An unreferenced asset returns 400.
stateMay be an empty string when the request carries images.
Count and sizeUp to 4 images for inworld/models/clairic; other models can differ. A request that carries images must fit in 4 MiB (4,194,304 bytes), or it returns 413.
ModelThe model's spec.inputModalities must include image.

With images, a text answer's span can index state with the reference keys removed. Set options.return_state_text to true to get the text that span positions refer to, as state_text.

Errors

Request validation returns 400 with error.type: "invalid_request_error" before the request reaches a model. For field and asset validation, error.param names the member to fix. Other errors can omit param.

For example, "fields": {"total": {"type": "money"}} returns:

json
{
  "error": {
    "message": "fields.total.type: unknown field type \"money\"; expected text, number, date, time, datetime, duration, list, estimate or forecast",
    "type": "invalid_request_error",
    "param": "fields.total.type"
  }
}

Errors from the model keep their HTTP status and use {"error": {"message": "...", "type": "..."}}: rate_limit_error for 429, timeout_error for 504 and api_error for other 5xx errors. When Inworld can't reach the model, the 502 uses upstream_error. Retry transient errors with exponential backoff and honor Retry-After when present.

Check the HTTP status and content type before parsing: 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. See Errors in the Extractions guide for every status and what to do.

Authorizations

Authorizationstringrequired

Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.

A standard API key can call chat completions, the Responses and Messages APIs, moderation and Decisions. To create, update or delete routers, the key also needs write permissions for the Router API. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Body

application/json

modelstringrequired

An extraction model: the id from the List models API with output_modalities=extractions, for example inworld/models/clairic. Chat and decision models are refused.

statestringrequired

The text to read. Write each asset's reference key where its image belongs. May be an empty string only when the request carries images. Input longer than the model's spec.contextLength is cut, and the response has truncated: true.

fieldsobjectrequired

The values to extract, keyed by names you choose. Each answer comes back under the same name. At least one field is required.

assetsobject

Images to read, keyed by a reference key you choose. Each key must appear in state or in some field's instructions as a standalone token: a letter, digit, _, . or - directly before or after it makes it part of a longer word, and an asset referenced nowhere returns 400. The model's spec.inputModalities must include image. inworld/models/clairic reads up to 4 images per request, and a request that carries images must fit in 4 MiB (4,194,304 bytes).

reference_datestring

The date the content was written, YYYY-MM-DD, used to resolve relative dates such as "yesterday" or "next Friday".

optionsobject

Optional extras in the response.

Show child attributes

include_quantilesboolean

Return the full quantiles array on estimate answers.

return_state_textboolean

Return state_text, the text that span positions index. With images, it is state with the reference keys removed.

Response

200 - application/json

modelstring

The model that answered. It can be a shorter form of the id you sent, such as inworld/clairic for inworld/models/clairic.

answersobject

One answer per field, keyed by the names used in fields.

truncatedboolean

true when the input was longer than the model's context and was cut. A field near the end may then be missing or guessed.

state_textstring

Present when options.return_state_text is true: the text span positions index.

usageobject

Token usage. Extractions are billed on input_tokens only. input_tokens can exceed the sum of the parts, because the model can read the input more than once (passes).

Show child attributes

state_tokensinteger

image_tokensinteger

schema_tokensinteger

Tokens for your field definitions.

input_tokensinteger

The billed count.

output_tokensinteger

Always 0; output is not billed.

passesinteger

How many times the model read the input.

metadataobject

Inworld request metadata, with the same keys as on chat completions.

Show child attributes

attemptsobject[]

Show child attributes

modelstring

status_codeinteger

duration_msnumber

successboolean

generation_idstring

Unique identifier for this request.

total_duration_msinteger

Total request duration in milliseconds.