Usage

All of our text generation models support the following endpoints:

• /v1/completions: OpenAI-compatible Completions API endpoint
• /v1/chat/completions: OpenAI-compatible Chat Completions API endpoint
• /v1/responses: OpenAI-compatible Responses API endpoint
• /v1/messages: Anthropic-compatible Messages API endpoint
• /v1/models: OpenAI-compatible endpoint to list the available models
• /completions: llama.cpp-style completions endpoint

💡 More endpoints will be provided in the future. If you have a specific need, feel free to contact us on Telegram!

This means that you can use our models with any of the OpenAI SDKs or with frameworks that support custom OpenAI-compatible models.

Examples

Basic chat completion

curl -X POST https://api.libertai.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "qwen3.6-35b-a3b",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Vision

curl -X POST https://api.libertai.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "qwen3.6-35b-a3b",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
            }
          }
        ]
      }
    ]
  }'

Streaming

Pass stream: true to receive tokens incrementally as they're generated. The endpoint emits server-sent events matching the OpenAI streaming format.

curl -N -X POST https://api.libertai.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "qwen3.6-35b-a3b",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Count from 1 to 5, one number per line." }
    ]
  }'

Function (tool) calling

Models flagged with ⚙️ on the models list support OpenAI-style tool calls.

from openai import OpenAI

client = OpenAI(base_url="https://api.libertai.io/v1", api_key="YOUR_API_KEY")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="qwen3.6-35b-a3b",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=tools,
)

tool_call = resp.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

After your code runs the tool, append a role: "tool" message with tool_call_id and content to the conversation and call the model again — same flow as the OpenAI API.

Anthropic Messages format

The /v1/messages endpoint accepts requests in Anthropic's Messages format, so the Anthropic SDK works against LibertAI by changing the base URL.

curl -X POST https://api.libertai.io/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen3.6-35b-a3b",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

Direct model interaction

You can bypass the api.libertai.io load balancer and talk to the machine serving a model, which cuts a hop and removes us from the path. How you do that depends on the model:

• An ordinary model is a host you call like any other HTTPS endpoint — Call a host directly.
• A 🔒 confidential model has no stable host, and you want to verify the hardware before sending anything, so it takes a verifying client — Confidential models.

Either way you lose the gateway's health-aware routing, and only the confidential path lets you check what you are talking to. Trust model & TEE covers what each layer protects against.

Discover the hosts for a model

The GET /libertai/models endpoint returns the list of servers currently backing each model:

curl https://api.libertai.io/libertai/models

{
  "qwen3.8-27b": {
    "servers": [
      "https://qwen-3-8-27b-1.models.libertai.io",
      "https://qwen3-5-27b-1.models.libertai.io"
    ]
  },
  "qwen3.8-27b-tee": {
    "servers": ["tee://a41744d4be9ac87b729608d3f22e35aa53081513de7d58a974c1a874d2e7b560"]
  },
  "z-image-turbo": {
    "servers": ["https://z-image-turbo-1.models.libertai.io"]
  }
}

A tee:// entry is not an address: it is the Aleph item hash of a confidential deployment, whose address is discovered and then attested. Reaching one directly means using a verifying client — see Confidential models below.

Each entry maps a model id (the same one you'd pass to /v1/chat/completions) to one or more server URLs. This endpoint covers every model exposed by LibertAI — text, image, etc. — so it's the same discovery path for any direct-host use case.

Call a host directly

The servers expose the same OpenAI-compatible endpoints (/v1/chat/completions, /v1/completions, /v1/messages, …) as the main API. Your LibertAI API key works on them too — keys are distributed to each backing server, so authenticate exactly the same way:

curl -X POST https://qwen-3-8-27b-1.models.libertai.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

Confidential models

A 🔒 model's servers entry is a tee://<item hash> rather than a URL, because a confidential deployment has no stable address: the node assigns a fresh port on every boot, and the certificate is regenerated each time. The verifying clients resolve the hash, attest the enclave and pin the certificate they proved, then hand you an HTTP client:

from openai import OpenAI
from libertai_confidential import connect

tee = connect(model="qwen3.8-27b-tee")
client = OpenAI(api_key="YOUR_API_KEY", base_url=tee.base_url, http_client=tee.http_client)

completion = client.chat.completions.create(
    model="qwen3.8-27b-tee",
    messages=[{"role": "user", "content": "Hello!"}],
)

Your API key still applies — it is checked inside the enclave — and attestation happens before the first byte of your request is written, so a server that fails verification is never sent a prompt. See Trust model & TEE for what each check establishes.

Things to know

• No load balancing or failover — when you call a host directly you lose the gateway's health-aware routing across multiple instances and the sticky-session cookie used for KV-cache locality. If a model has several servers, your client is responsible for choosing one and retrying on another if it fails.
• Hosts can change — the servers list reflects the network's current state. Re-query /libertai/models periodically rather than hardcoding URLs.
• TEE confidentiality — for models running in a TEE (look for 🔒 on the models list), calling the enclave directly removes every party but the enclave itself, LibertAI included, and lets your client verify the hardware before it sends anything. See Trust model & TEE.

Verifying your API key

GET /libertai/auth/check returns 200 OK if your key is valid, 401 Unauthorized otherwise — useful for sanity-checking configuration during onboarding without spending tokens.

curl -i https://api.libertai.io/libertai/auth/check \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Status	Meaning	What to do
401	Missing or invalid API key	Verify your key in the Console or via /libertai/auth/check
402	Payment required (x402 flow)	Sign and resubmit with X-PAYMENT — see x402
404	Unknown model	Pull the list from /v1/models or /libertai/models
422	Validation error	Check field types and enum values
503	All servers failed for this model	Retry shortly — the gateway tried every CRN and none responded

Errors return JSON of the form {"detail": "..."}. Streaming responses can fail mid-stream — handle error events in your SSE consumer.

See also

• Available models & pricing
• Direct CRN access
• x402 payments — pay per request without an API key
• Trust model & TEE
• Architecture