Alpha.Extractions - OpenRouter | Documentation

Overview

Alpha feature endpoints for Extractions requests

Available Operations

create - Submit an Extractions request

create

Extracts, computes, estimates or forecasts typed fields from a state string and image assets using an extraction-style System One model. Alpha: the shape is not stable.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.alpha.extractions.create(fields={
        "contacts": {
            "items": "text",
            "type": "list",
        },
        "days_to_pay": {
            "max": 120.0,
            "min": 0.0,
            "step": 1.0,
            "type": "estimate",
        },
        "due_date": {
            "instructions": "Issue date plus the net payment days",
            "type": "date",
        },
        "invoice_number": {
            "type": "text",
        },
        "total": {
            "decimals": 2,
            "type": "number",
            "unit": "USD",
        },
    }, model="cloudflare/clairic", state="Invoice INV-2291 issued 2026-09-02, net 30. Contacts: Dana Ruiz, Priya Shah. Total $1080.", reference_date="2026-10-28")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`fields`	Dict[str, components.Fields]	✔️	Map of field name to typed field spec.
`model`	str	✔️	N/A
`state`	str	✔️	The text to read from. May be empty only when the request carries image assets.
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`assets`	Dict[str, components.DecisionsImageAsset]	➖	Images keyed by reference string, as in TypeSafe’s API. Write a reference wherever the image belongs in `state`, `instructions`, or `criteria`; every asset must be referenced at least once. Jev reads a reference as a whole string value or inside longer text. Other Decisions models read a whole-string reference wherever they read an `image_url` part and reject a reference inside longer text.
`provider`	OptionalNullable[components.ProviderPreferences]	➖	N/A	{ “allow_fallbacks”: true }
`reference_date`	Optional[str]	➖	ISO date that anchors dates written without a year.
`session_id`	Optional[str]	➖	A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.	session-1234
`trace`	Optional[components.TraceConfig]	➖	Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.	{ “trace_id”: “trace-abc123”, “trace_name”: “my-app-trace” }
`user`	Optional[str]	➖	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.
`server_url`	Optional[str]	➖	An optional server URL to use.	http://localhost:8080

Response

components.ExtractionsResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.PaymentRequiredResponseError	402	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.PayloadTooLargeResponseError	413	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.EdgeNetworkTimeoutResponseError	524	application/json
errors.ProviderOverloadedResponseError	529	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/