Guide

Quickstart

Get a key, make one call, read the reply, and find the usage it produced.

Base Eleven's models are fictional and its API returns simulated responses. Usage, credits and billing run for real, in test mode.

1. Get a key

Sign in and open the keys page. Keys belong to a workspace, not a person: anyone in the workspace can create or revoke one, and every call is metered to the workspace. A new workspace starts on the Free trial, with $5 in credits for 14 days and no card.

A key is b11_sk_ followed by 32 letters and digits. It is shown once, when you create it; only a keyed hash is kept, so a lost key is revoked and replaced, never recovered. Keep it on your server. Browsers cannot call the API from another origin.

The examples read the key from the B11_API_KEY environment variable.

2. Make a call

POST https://api.baseeleven.dev/v1/messages with a JSON body: the model, the most output tokens you want (max_tokens), and the conversation so far as messages, oldest first. The first message is always the user’s. This call asks Eleven Lite (eleven-lite) for a short answer.

curl

curl https://api.baseeleven.dev/v1/messages \
  -H "x-api-key: $B11_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "model": "eleven-lite",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Summarise this month of token usage in three short bullet points."
    }
  ]
}'

Python (standard library)

import json
import os
import urllib.request

API_URL = "https://api.baseeleven.dev/v1"

body = {
    "model": "eleven-lite",
    "max_tokens": 256,
    "messages": [
        {
            "role": "user",
            "content": "Summarise this month of token usage in three short bullet points.",
        },
    ],
}

request = urllib.request.Request(
    f"{API_URL}/messages",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "x-api-key": os.environ["B11_API_KEY"],
        "content-type": "application/json",
    },
    method="POST",
)

# A 4xx or 5xx raises urllib.error.HTTPError; its body is the JSON error, read it with e.read().
with urllib.request.urlopen(request) as response:
    print(response.status, response.headers.get("request-id"))
    print(json.dumps(json.load(response), indent=2))

TypeScript (fetch)

// first-call.ts: one call to the API with fetch. Save it, then run:
//   B11_API_KEY=<your key> npx tsx first-call.ts

const API_URL = 'https://api.baseeleven.dev/v1';

const apiKey = process.env.B11_API_KEY;
if (apiKey === undefined || apiKey === '') {
  throw new Error('Set B11_API_KEY to a key from the keys page.');
}

const body = {
  model: 'eleven-lite',
  max_tokens: 256,
  messages: [
    {
      role: 'user',
      content: 'Summarise this month of token usage in three short bullet points.',
    },
  ],
};

const response = await fetch(`${API_URL}/messages`, {
  method: 'POST',
  headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
  body: JSON.stringify(body),
});

// Every response carries a request-id; quote it when you ask for help.
console.log(response.status, response.headers.get('request-id'));

// 200: {id, type: "message", model, content: [{type: "text", text}], stop_reason, usage}.
// Anything else: {type: "error", error: {type, message, b11_code}, request_id}.
const reply: unknown = await response.json();
console.log(JSON.stringify(reply, null, 2));

export {};

Optional fields: system (instructions, a string or text blocks), temperature and top_p (0 to 1), stop_sequences (up to 4) and stream. A field the API does not define is refused with 400 invalid_field, naming the field.

3. Read the reply

A 200 is one JSON object. content holds the reply as text blocks; stop_reason says why it ended (end, max_tokens or stop_sequence); usage holds the tokens you are charged for. This reply is the simulator’s own, cut short by a small max_tokens:

200 OK

{
  "id": "msg_01M3VNBWG00M2GA1850M2GA185",
  "type": "message",
  "model": "eleven-lite",
  "content": [
    {
      "type": "text",
      "text": "Simulated reply: placeholder text, not written by any model.\n\nRi"
    }
  ],
  "stop_reason": "max_tokens",
  "usage": {
    "input_tokens": 3,
    "output_tokens": 16
  }
}

Anything other than a 200 is an error body: {"type": "error", "error": {"type", "message", "b11_code"}, "request_id"}. Branch on b11_code; the errors page lists every one.

Replies are simulated placeholder text. Their first line says so, and their length, speed and shape follow the model’s profile on the models page. A reply never depends on anything but the request, so the same request gives the same reply.

4. Find the usage

The call’s input and output tokens are priced at list the moment it ends and debited from the workspace. The usage page shows tokens and cost by day and by model, next to the balance, and catches up within minutes. The response’s usage is the same count.

Prompts and replies are never logged or stored; only the token counts are. Rate limits and the per-tier numbers are on the tiers page; what each outcome costs is on the credits page.

Next: Streaming