MODELAXY API / V1

One contract for every intelligence workload.

Build with native Modelaxy controls or existing OpenAI clients. Every response stays on a stable public service profile while private execution remains private.

Base URLhttps://api.modelaxy.comAuthenticationAuthorization: Bearer $MODELAXY_API_KEY

API explorer

Send a workspace API key as a Bearer token. Full key secrets are displayed once and are never recoverable.

OpenAI compatible

Responses

A modern response contract for text generation, structured input, instructions, and streaming.

StreamingFunction callingStructured inputImages, PDF, and audioPrivacy policyExact cacheIdempotent retriesCustom attributionW3C workflow traces

Request

curl -X POST "https://api.modelaxy.com/v1/responses" \
  -H "Authorization: Bearer $MODELAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "tokenlab-general",
  "input": "What is the weather in Paris?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string"
          }
        },
        "required": [
          "location"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}'

Request

Bearer API key

FieldTypeRequirementDescription

modelstringRequired

A stable Modelaxy service profile.

inputstring | message[]Required

Plain text, role-based text/media messages, function_call items, or function_call_output items.

instructionsstringOptional

High-level behavior for this response.

toolsfunction[]Optional

JSON Schema function definitions. Modelaxy returns normalized calls; your application executes them.

tool_choicestring | objectOptional

auto, none, required, or one named function.

parallel_tool_callsbooleanOptional

Allow more than one function call in one response.

streambooleanOptional

Return typed server-sent events.

tokenlab.privacystringOptional

managed, zero_retention, or local_only.

Response

application/json

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "tokenlab-general",
  "output": [{
    "type": "function_call",
    "call_id": "call_...",
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris\"}",
    "status": "completed"
  }],
  "output_text": "",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 86,
    "total_tokens": 110
    }
}

Run large workloads on your schedule

Submit durable Responses API jobs without holding an HTTP connection open. Every item keeps the same Modelaxy policy, billing, routing, and provider-privacy boundary.

01
Submit up to 1,000 requests with unique custom_id values.
02
Monitor item counts or subscribe to terminal webhook events.
03
Download encrypted results as NDJSON and correlate by custom_id.

curl -X POST "https://api.modelaxy.com/v1/batches" \
  -H "Authorization: Bearer $MODELAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "/v1/responses",
    "completion_window": "24h",
    "requests": [{
      "custom_id": "case-001",
      "body": {
        "model": "tokenlab-general",
        "input": "Summarize this record."
      }
    }]
  }'

Queued requests are encrypted and removed item by item after execution. Results are user-deletable and retained from one hour to seven days.

Choose intent, not a vendor

Service profiles describe the behavior your application needs. Modelaxy can improve the private execution plan without changing your integration.

tokenlab-fast

Interactive, low-latency execution.

tokenlab-general

Balanced production default.

tokenlab-reasoning

Multi-pass evaluation and synthesis.

tokenlab-private

Hard local-only execution boundary.

tokenlab-embedding

Normalized semantic vectors with a stable, opaque space ID.

Tools stay under your control

Declare functions with JSON Schema through Chat Completions or Responses. Modelaxy returns a validated, provider-neutral call ID and arguments; your application approves and executes the function, then sends the result back for the final answer.

01
Send the available function definitions with the user request.
02
Execute only the returned calls your application allows.
03
Return each result with its opaque call ID to continue the conversation.

const tools = [{
    type: "function",
    function: {
      name: "get_weather",
      parameters: {
        type: "object",
        properties: { location: { type: "string" } },
        required: ["location"],
        additionalProperties: false
      }
    }
  }];

const first = await client.chat.completions.create({
  model: "tokenlab-general",
  messages,
  tools
});

const call = first.choices[0].message.tool_calls?.[0];
const output = await executeApprovedTool(call);

const final = await client.chat.completions.create({
  model: "tokenlab-general",
  messages: [
    ...messages,
    first.choices[0].message,
    { role: "tool", tool_call_id: call.id, content: output }
  ],
  tools
});

Modelaxy never runs arbitrary customer functions. Tool definitions and tool-history requests bypass exact response caching.

Keep every index in one vector space

Every embedding response includes an opaque embedding_space ID. Store it with your index and pin it on later writes. If the underlying space changes, Modelaxy returns 409 instead of silently mixing incompatible vectors.

x-modelaxy-embedding-space: mxes_...

{
  "model": "tokenlab-embedding",
  "input": "A document to index",
  "tokenlab": {
    "embedding_space": "mxes_..."
  }
}

The identifier proves compatibility without exposing the provider or private model.

Stable, traceable errors

Every error includes a public code and request ID. Internal provider, model, and deployment identifiers are never included.

{
  "error": {
    "code": "TL_CAPACITY_BUSY",
    "message": "Modelaxy capacity is temporarily busy.",
    "request_id": "req_..."
  }
}

Reuse exact outputs without weakening privacy

When your workspace enables exact caching, identical managed requests can return encrypted cached answers or vectors at lower latency and cost. Private, local-only, and zero-retention traffic always bypasses it.

x-modelaxy-cache: default | bypass | refresh
x-modelaxy-cache-ttl: 60..2592000

x-modelaxy-cache-status: DISABLED | BYPASS | MISS | REFRESH | HIT
x-modelaxy-cache-age: 42

Use x-modelaxy-cache to bypass or refresh a request, and x-modelaxy-cache-ttl to shorten its TTL. Every response reports x-modelaxy-cache-status.

Your requested boundary is enforced

Use local_only to exclude managed cloud execution. If compliant local capacity is unavailable, the request fails instead of silently falling back.

Open the API Center