Skip to main content
POST
/
v1
/
inference
Execute Raw Inference
curl --request POST \
  --url https://api.mixpeek.com/v1/inference \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {},
  "provider": "openai",
  "model": "gpt-4o-mini",
  "inference_name": "my_text_embedder_1_0_0",
  "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
  "parameters": {
    "max_tokens": 500,
    "temperature": 0.7
  },
  "enable_semantic_cache": false,
  "cache_delta": 0.5
}
'
{
  "data": "<unknown>",
  "provider": "<string>",
  "model": "<string>",
  "latency_ms": 123,
  "tokens_used": {
    "completion": 120,
    "prompt": 15,
    "total": 135
  },
  "cached": false
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
X-Namespace
string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Body

application/json

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} }

# Text embedding (provider + model)
{
    "provider": "openai",
    "model": "text-embedding-3-large",
    "inputs": {"text": "machine learning"},
    "parameters": {}
}

# Custom plugin (inference_name)
{
    "inference_name": "my_text_embedder_1_0_0",
    "inputs": {"text": "hello world"},
    "parameters": {}
}

# Audio transcription
{
    "provider": "openai",
    "model": "whisper-1",
    "inputs": {"audio_url": "https://example.com/audio.mp3"},
    "parameters": {}
}

# Vision (multimodal)
{
    "provider": "openai",
    "model": "gpt-4o",
    "inputs": {
        "prompts": ["Describe this image"],
        "image_url": "https://example.com/image.jpg"
    },
    "parameters": {"temperature": 0.5}
}
​
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:
{
  "prompts": ["What is the capital of France?"]
}
{ "text": "machine learning" }
{
  "audio_url": "https://example.com/audio.mp3"
}
​
provider
string | null

Provider name: openai, google, 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

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

Example:
{ "max_tokens": 500, "temperature": 0.7 }
​
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

Token usage statistics (if available)

Example:
{
  "completion": 120,
  "prompt": 15,
  "total": 135
}
​
cached
boolean
default:false

Whether the response was served from semantic cache (vCache)