Skip to main content
POST
Execute Raw Inference

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace
string
header
required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request for raw inference without retriever framework.

This endpoint provides direct access to inference services with minimal configuration. Ideal for simple LLM calls, embeddings, transcription, or vision tasks without requiring collection setup or retriever configuration.

You can either use:

  • provider + model for standard providers (openai, google, anthropic)
  • inference_name for custom plugins

Examples: # Chat completion (provider + model) { "provider": "openai", "model": "gpt-4o-mini", "inputs": {"prompts": ["What is AI?"]}, "parameters": {"temperature": 0.7, "max_tokens": 500} }

inputs
Inputs · object
required

Model-specific inputs. Chat: {prompts: [str]}, Embeddings: {text: str} or {texts: [str]}, Transcription: {audio_url: str}, Vision: {prompts: [str], image_url: str}

Examples:
provider
string | null

Provider name: openai, google (or its alias gemini), anthropic (required if inference_name not set)

Example:

"openai"

model
string | null

Model identifier specific to the provider (required if inference_name not set)

Example:

"gpt-4o-mini"

inference_name
string | null

Custom plugin inference name (alternative to provider+model)

Example:

"my_text_embedder_1_0_0"

feature_uri
string | null

Feature URI to resolve to inference_name (alternative to inference_name). Format: mixpeek://{extractor}@{version}/{vector_index_name}

Example:

"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"

parameters
Parameters · object | null

Optional parameters for inference. Common: temperature (float), max_tokens (int), schema (dict for structured output)

Example:
enable_semantic_cache
boolean
default:false

Enable semantic caching (vCache) for LLM chat operations. When enabled, semantically similar prompts may return cached responses, reducing latency and cost. Only applies to chat/completion models.

cache_delta
number | null

Maximum error rate for semantic cache (0.0-1.0). Lower values are more conservative. Default uses system setting (0.02 = 2%).

Required range: 0 <= x <= 1

Response

Successful Response

Response from raw inference.

Returns the inference results along with metadata about the request.

data
any
required

Inference results (structure varies by modality)

provider
string
required

Provider that was used

model
string
required

Model that was used

latency_ms
number
required

Total inference latency in milliseconds

tokens_used
Tokens Used · object | null

Token usage statistics (if available)

Example:
cached
boolean
default:false

Whether the response was served from semantic cache (vCache)