API Reference

Beast speaks the OpenAI API. Point any OpenAI-compatible client at https://api.beastlab.ai/v1 and use a Beast model id. Both /v1/chat/completions and /v1/responses are supported.

This page covers calling the API directly. If you want to wire Beast into a coding tool instead — Cursor, Kilo Code CLI, OpenCode and friends — see Integrations.

Authentication

Generate an API key in the BeastLab Portal, then export it so your shell can pick it up:

export BEASTLAB_API_KEY="sk-beast-..."

Every request carries it as a bearer token: Authorization: Bearer $BEASTLAB_API_KEY.

Quick start

The smallest useful call — a model, a message, and the two parameters most people reach for:

curl --max-time 7200 https://api.beastlab.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEASTLAB_API_KEY" \
  -d '{
    "model": "beast-mini",
    "messages": [{"role": "user", "content": "Hello, Beast!"}],
    "reasoning_effort": "high",
    "web_search_options": {"search_context_size": "medium"}
  }'

reasoning_effort controls how hard Beast thinks. web_search_options lets it search the web. Both are optional — everything below is too.

Models

Swap the model field to change tier. See Models for context windows, pricing, and full specs.

Reasoning

Set reasoning_effort to trade latency and cost for depth. Higher levels engage a deeper reasoning path, take longer, and cost more.

Default: unset. Omit the field and each model reasons at its own built-in depth. That is not the same as sending "medium", which explicitly pins the depth across the request.

An effort a model does not list is rejected with a 400 naming the model — it is never silently downgraded to a supported level.

Both endpoints also accept the nested OpenAI shape "reasoning": {"effort": "xhigh"}, so official SDKs work unchanged. Top-level reasoning_effort wins if you send both.

Web search

Default: off. Beast does not search the web unless you opt in with web_search_options, and you must name an explicit search_context_size to turn it on. More context means more sources retrieved, at higher cost.

"web_search_options": {"search_context_size": "high"}

Accepts "low", "medium", or "high". Omit the field entirely to disable search. An empty object ({}) also leaves search off — it is not shorthand for "on". Sending false is rejected: the value must be an object or absent.

Structured outputs

Constrain the answer to a JSON schema. Both endpoints support it — they just spell it differently. Chat Completions uses response_format; the Responses API uses text.format.

// Chat Completions
"response_format": {
  "type": "json_schema",
  "json_schema": {"name": "ceo", "strict": true, "schema": { ... }}
}

// Responses
"text": {
  "format": {"type": "json_schema", "name": "ceo", "strict": true, "schema": { ... }}
}

Plain JSON mode ({"type": "json_object"}) works on both as well, and structured outputs combine safely with web_search_options.

Streaming

Set "stream": true for a server-sent-event stream, on either endpoint. Beast streams the final answer as it is produced.

curl -N --max-time 7200 https://api.beastlab.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEASTLAB_API_KEY" \
  -d '{
    "model": "beast-mini",
    "messages": [{"role": "user", "content": "Explain CRDTs briefly."}],
    "stream": true
  }'

Chat Completions — full example

curl --max-time 7200 https://api.beastlab.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEASTLAB_API_KEY" \
  -d '{
    "model": "beast-max",
    "messages": [
      {"role": "user", "content": "Summarise the latest AI releases."}
    ],
    "reasoning_effort": "vhigh",
    "web_search_options": {"search_context_size": "high"},
    "stream": true,
    "temperature": 0.7,
    "max_tokens": 32768,
    "response_format": {"type": "json_object"},
    "seed": 42
  }'

Responses API — full example

curl --max-time 7200 https://api.beastlab.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEASTLAB_API_KEY" \
  -d '{
    "model": "beast-max",
    "input": "Summarise the latest AI releases.",
    "reasoning_effort": "vhigh",
    "web_search_options": {"search_context_size": "high"},
    "stream": true,
    "temperature": 0.7,
    "max_output_tokens": 32768
  }'

Parameter reference

Every parameter is optional — a request carrying only model and messages (or input) runs with the defaults below.

Using an SDK

Any OpenAI-compatible SDK works — just override the base URL.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.beastlab.ai/v1",
    api_key=os.environ["BEASTLAB_API_KEY"],
    timeout=7200,
)

resp = client.chat.completions.create(
    model="beast-max",
    messages=[{"role": "user", "content": "Hello, Beast!"}],
    reasoning_effort="xhigh",
    extra_body={"web_search_options": {"search_context_size": "high"}},
)
print(resp.choices[0].message.content)

Tips

• Give it time. Beast deliberates before answering, and high-effort requests can run for many minutes. Keep a generous client timeout — the examples above use --max-time 7200.
• Images ride image_url parts in message content; beast-max also accepts PDFs and documents.
• Cost scales with effort. vhigh, xhigh and yolo buy depth at a real price — start lower and raise it only where quality matters.
• Wiring Beast into an editor or agent harness? Start with Integrations.