Extractions
Create extraction
Extract typed fields from text or images
/alpha/extractionsPreview. 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:
{
"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 constraint | Accepted values and behavior |
|---|---|
format | png, jpg, jpeg or webp. pdf and type: document return 400: render PDF pages to images first. |
data_base64 | Standard base64 of the image bytes, with no data: prefix. |
| Reference 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. An unreferenced asset returns 400. |
state | May be an empty string when the request carries images. |
| Count and size | Up 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. |
| Model | The 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:
{
"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.
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.
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.
The values to extract, keyed by names you choose. Each answer comes back under the same name. At least one field is required.
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).
The date the content was written, YYYY-MM-DD, used to resolve relative dates such as "yesterday" or "next Friday".
The model that answered. It can be a shorter form of the id you sent, such as inworld/clairic for inworld/models/clairic.
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.
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).
Inworld request metadata, with the same keys as on chat completions.