---
title: "Run inference (Pioneer native)"
method: POST
path: "/inference"
tags: ["inference"]
---

# Run inference (Pioneer native)

`POST /inference`

Unified inference endpoint for encoder tasks (NER, text classification, JSON extraction) and decoder tasks (text generation). Discriminated by the presence of a `messages` field: include `messages` for decoder generation; use `text` + `schema` for encoder tasks.

## Request body

- union
  - EncoderInferenceRequest — Request for encoder (GLiNER) tasks. Discriminated from GenerateInferenceRequest by the absence of a `messages` field.
    - `model_id` string, required — Training job UUID, project name, or base encoder model ID (e.g. `fastino/gliner2-base-v1`).
    - `text` union, required — Input text or list of texts for batch processing.
      - string
      - string[]
    - `schema` union, required — Extraction schema. Use the unified dict form: `{"entities": [{"name": "organization"}]}`.
      - object — Unified extraction schema dict with keys: entities, classifications, structures, relations.
      - string[] — Deprecated flat entity label list. Use the dict form instead.
    - `threshold` number — Confidence threshold for predictions.
    - `include_confidence` boolean
    - `include_spans` boolean — Include character-level start/end positions.
    - `store` boolean — Persist to inference history. Set false to opt out.
    - `project_id` string — Project ID for attribution and auto-improvement.
  - GenerateInferenceRequest — Request for decoder text generation. Discriminated from EncoderInferenceRequest by the presence of a `messages` field.
    - `model_id` string, required — Training job UUID, project name, or base decoder model ID (e.g. `Qwen/Qwen3-8B`).
    - `task` 'generate', required
    - `messages` object[], required — Chat messages. The last message must have role `"user"`.
      - `role` 'system' | 'user' | 'assistant', required
      - `content` string, required
    - `max_tokens` integer
    - `temperature` number
    - `top_p` number
    - `reasoning` ReasoningConfig — Opt-in reasoning / extended-thinking controls. Normalized across providers — Anthropic (`thinking`), OpenAI/Fireworks (`reasoning_effort`), OpenRouter (`reasoning`). Pioneer does not enable reasoning by default.
      - `enabled` boolean — Set false to explicitly disable thinking on models that have it on by default.
      - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'none' — OpenAI/Grok-style effort tier. Mutually exclusive with `max_tokens`.
      - `max_tokens` integer — Anthropic-style reasoning budget in tokens. Mutually exclusive with `effort`.
      - `mode` 'manual' | 'adaptive' — Anthropic extended-thinking dispatch mode. Leave unset to let Pioneer pick the per-model default.
      - `display` 'summarized' | 'omitted' — Whether thinking text streams back (`summarized`) or is omitted to save latency (`omitted`).
      - `exclude` boolean — Model reasons internally but reasoning tokens are not returned to the caller.
    - `include_reasoning_trace` boolean — Return extracted `<think>` trace text separately in the response.
    - `store` boolean — Persist to inference history. Set false to opt out.
    - `project_id` string

## Response `200`

Inference result. `type` is `"encoder"` for encoder tasks and `"decoder"` for generation.

- union
  - EncoderInferenceResponse
    - `type` 'encoder', required
    - `inference_id` string, required — Unique inference ID. Use with GET /inferences/{inference_id} or POST /inferences/{inference_id}/feedback.
    - `result` object, required — Extraction result. Shape depends on the schema and task.
    - `model_id` string, required
    - `latency_ms` number, required — Server-side inference latency in milliseconds.
    - `token_usage` integer, required — Input tokens processed.
    - `model_used` string, required — Resolved model identifier.
  - GenerateInferenceResponse
    - `type` 'decoder', required
    - `inference_id` string, required — Unique inference ID.
    - `completion` string, required — Generated text.
    - `reasoning_trace` string — Extracted `<think>` reasoning trace when `include_reasoning_trace=true`.
    - `model_id` string, required
    - `latency_ms` number, required

## Other responses

- `401` — Missing or invalid API key.
- `402` — Insufficient credits or no active billing plan.
- `404` — Model ID not found or not yet deployed.
- `422` — Request body failed schema validation.
- `429` — Rate limit exceeded. Retry after the duration in the `Retry-After` response header.

---

[API](https://skmtc.net/fastino-ai/apis/pioneer-inference-api.md) · [All operations](https://skmtc.net/fastino-ai/apis/pioneer-inference-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fastino-ai/pioneer-inference-api/versions/2541b0de636c/schema)