Python OpenAI SDK with FreeBrain

Use the Python openai package with FreeBrain by setting api_key to a FreeBrain key and base_url to https://api.thefreebrain.com/v1. This guide calls Chat Completions from a server or local terminal and includes an optional streaming mode.

Prepare Python and a chat model

Use Python 3.10 or later. Create a FreeBrain API key, then choose a model that supports /v1/chat/completions in the model catalog. Copy its exact ID; a model's display name may differ from its API ID. Your key's group, model restrictions, and remaining quota must permit the request.

The examples below use openai==3.11.0. Install it in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'openai==3.11.0'
export FREEBRAIN_API_KEY='YOUR_FREEBRAIN_API_KEY'
export FREEBRAIN_MODEL='YOUR_CHAT_MODEL_ID'

These terminal commands use macOS/Linux shell syntax. On Windows, activate the virtual environment and set the same variables using your shell's syntax. Keep keys in server-side environment variables, never browser bundles or source control. Generation requests can consume your balance.

Send a request or stream text

Save this as freebrain_chat.py. Run python freebrain_chat.py for a complete response, or python freebrain_chat.py --stream to print text as chunks arrive.

import argparse
import os
import sys

from openai import APIConnectionError, APIStatusError, OpenAI

parser = argparse.ArgumentParser()
parser.add_argument("--stream", action="store_true")
args = parser.parse_args()
api_key = os.environ.get("FREEBRAIN_API_KEY")
model = os.environ.get("FREEBRAIN_MODEL")
if not api_key or not model:
    sys.exit("Set FREEBRAIN_API_KEY and FREEBRAIN_MODEL first.")

try:
    with OpenAI(
        api_key=api_key,
        base_url="https://api.thefreebrain.com/v1",
        timeout=60.0,
        max_retries=0,
    ) as client:
        reply = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": "Say hello in one sentence."}],
            stream=args.stream,
        )
        if args.stream:
            finish_reason = None
            with reply:
                for chunk in reply:
                    if not chunk.choices:
                        continue
                    choice = chunk.choices[0]
                    if choice.delta.content:
                        print(choice.delta.content, end="", flush=True)
                    if choice.finish_reason is not None:
                        finish_reason = choice.finish_reason
            print()
            if finish_reason is None:
                raise RuntimeError("Stream ended without a finish reason; output may be incomplete.")
        else:
            choice = reply.choices[0]
            print(choice.message.content or "")
            finish_reason = choice.finish_reason
        if finish_reason != "stop":
            print(f"Finish reason: {finish_reason}; inspect the result before using it.", file=sys.stderr)
except APIStatusError as error:
    print(f"HTTP {error.status_code}; request ID: {error.request_id or 'not provided'}", file=sys.stderr)
    sys.exit(1)
except APIConnectionError:
    sys.exit("Connection failed or timed out. Check the network and request status before retrying.")
except Exception as error:
    print(f"Request failed: {error}", file=sys.stderr)
    sys.exit(1)

The SDK appends /chat/completions to base_url. Do not put the complete endpoint in base_url or add a second /v1. Setting the key and URL explicitly also avoids accidentally sending a FreeBrain key to the default OpenAI endpoint.

Read streaming responses correctly

With stream=False, text is in choices[0].message.content. With stream=True, text arrives in choices[0].delta.content. A chunk can contain a role, an empty delta, or no choices; those chunks are not printable text. The example handles each case and checks that a finish reason arrived.

A finish reason of length means the output stopped at a limit. Tool-call responses need a separate tool execution loop; this example deliberately sends no tools and prints only text. Optional fields such as usage in the final chunk depend on the model and request options. See the Chat Completions reference before adding them.

Timeouts, retries, and errors

The example uses a 60-second SDK timeout and disables automatic retries so a failed trial is easy to diagnose. The timeout does not guarantee a generation has stopped upstream. In an application, choose timeouts for the model, use bounded retries only for suitable transient failures, and account for potentially duplicated work. A stream that fails after printing some text leaves partial output; do not mark it complete or append a fresh response to it blindly.

For account setup and a cURL comparison, use the quickstart. For additional error causes, use API troubleshooting. If you are moving an existing application, follow the migration checklist; for JavaScript, use the Node.js SDK guide.

Example verification

These examples are maintained in the FreeBrain repository. Automated checks execute the published code with the real Python SDK against a local HTTP fixture, including complete responses, streaming chunks, and failures. This verifies client configuration and response handling; it does not establish that a particular model is enabled for your account or measure live model performance.

SDK configuration and exceptions are documented in the official OpenAI Python library reference. FreeBrain endpoint and account behavior are covered by the FreeBrain references linked above.