Quickstart

Create a key, select a model and send a request. These examples use Chat Completions.

1. Create an API key

Sign in to your Tokamak workspace, select the organization for your application, and open API Keys. Create an inference key and save it securely.

Load the key into your environment as TOKAMAK_API_KEY. Do not put it in source code or a public browser application.

2. Choose a model

Use Bash and curl to list the deployed catalog:

curl -sS https://api.tokamak.sh/v1/models \
  -H "Authorization: Bearer $TOKAMAK_API_KEY"

Choose an entry's id that supports Chat Completions and set it as TOKAMAK_MODEL:

export TOKAMAK_MODEL="YOUR_MODEL_ID"

Use the exact ID from the catalog. Model availability and supported features can differ by environment.

3. Send a request

Each example reads the key and model from environment variables.

curl

The following is a Bash example. In PowerShell, use curl.exe with PowerShell quoting, or use the Python example.

curl -sS https://api.tokamak.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKAMAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TOKAMAK_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Say hello.\"}],
    \"max_tokens\": 64
  }"

Python

This example uses Python's standard library; no package installation is needed.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

base_url = os.environ.get("TOKAMAK_BASE_URL", "https://api.tokamak.sh/v1")
payload = {
    "model": os.environ["TOKAMAK_MODEL"],
    "messages": [{"role": "user", "content": "Say hello."}],
    "max_tokens": 64,
}
request = Request(
    f"{base_url.rstrip('/')}/chat/completions",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['TOKAMAK_API_KEY']}",
        "Content-Type": "application/json",
    },
)

try:
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    print(result["choices"][0]["message"]["content"])
except HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: {error.read().decode()}")

JavaScript

Run this in Node.js with built-in fetch. Keep it on your server or trusted local machine.

const baseURL = process.env.TOKAMAK_BASE_URL ?? "https://api.tokamak.sh/v1";
const apiKey = process.env.TOKAMAK_API_KEY;
const model = process.env.TOKAMAK_MODEL;
if (!apiKey || !model) throw new Error("Set TOKAMAK_API_KEY and TOKAMAK_MODEL");

const response = await fetch(`${baseURL.replace(/\/$/, "")}/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model,
    messages: [{ role: "user", content: "Say hello." }],
    max_tokens: 64,
  }),
  signal: AbortSignal.timeout(60_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const result = await response.json();
console.log(result.choices[0].message.content);

The examples use max_tokens. If your chosen model requires max_completion_tokens, use that field instead.

Read the response

For a successful text completion, read choices[0].message.content. A tool call or another endpoint has a different response structure; handle the format you requested.

If a request fails, check the HTTP status and error body. See Errors and debugging.