Connect an OpenAI-Compatible App to FreeBrain

Move a Chat Completions integration to FreeBrain. Map the API key, base URL, model ID, streaming behavior, and optional parameters before switching traffic.

An application using the OpenAI Chat Completions request format can connect to a compatible FreeBrain model by configuring a FreeBrain key, the base URL https://api.thefreebrain.com/v1, and the model's exact ID. Compatibility must be checked for the endpoint and features your application actually uses.

This guide is for an existing application or SDK integration. For a first request, start with the cURL quickstart. For runnable code, choose the Python SDK tutorial or Node.js SDK tutorial.

Map the connection settings

Setting	FreeBrain configuration	What to verify
API key	A key created in FreeBrain API keys	Keys are provider-specific; do not reuse a different provider's key.
API host	`https://api.thefreebrain.com`	Use HTTPS and the API subdomain.
OpenAI SDK base URL	`https://api.thefreebrain.com/v1`	Python uses `base_url`; JavaScript uses `baseURL`.
Complete chat endpoint	`https://api.thefreebrain.com/v1/chat/completions`	Use this only when the app asks for a complete endpoint URL.
Model	Exact model ID from the catalog	Confirm `/v1/chat/completions` support and your key's access.
Authentication header	`Authorization: Bearer YOUR_FREEBRAIN_API_KEY`	The official SDK sets this from its API-key option.

Configuration fields vary between apps. If an app appends /v1/chat/completions itself, its host field should contain only https://api.thefreebrain.com. If it appends /chat/completions, use the /v1 base URL. Inspect the resulting request URL instead of repeatedly adding or removing path segments by guesswork.

Identify the protocol before changing the URL

Check the method your application calls. client.chat.completions.create(...) uses Chat Completions. client.responses.create(...) uses the Responses API, which has a different request body, response structure, and streaming events. Anthropic Messages is another protocol. A shared SDK or gateway does not make those methods interchangeable.

For this migration, choose a model whose catalog entry supports Chat Completions. If your existing application uses Responses, Messages, image generation, or another endpoint, check that endpoint and model together before changing the connection settings. A model appearing in GET /v1/models is not evidence that every endpoint or optional feature is supported.

Test the smallest request first

Create a dedicated FreeBrain key with a suitable quota and model permissions. Keep the existing provider's key separate.
Select a chat model and copy its exact ID. Confirm billing units and rates in the catalog and your account's group.
Send the minimal text request from the quickstart, with no optional parameters. Confirm that the response contains the expected assistant text.
Run the same prompt through your actual application. Confirm that the request reaches /v1/chat/completions and that your response reader uses choices[0].message.content.
Enable optional features one at a time. Compare the behavior against the needs of your application before switching production traffic.

These are billable generation checks, so use a small, deliberate test set. Successful authentication proves neither answer quality nor support for every feature.

Check the features your application depends on

Feature	Migration check
Text and message roles	Test the message roles your model accepts and a representative multi-turn conversation.
Streaming	Read `delta.content`; handle empty chunks and an interrupted stream. Do not reuse Responses API event handlers.
Tool calls	Check tool schema support, returned tool-call IDs, argument parsing, and the follow-up tool-result message.
Structured output	Verify the specific JSON or schema option for the selected model; parse and validate the actual result.
Images or other input types	Confirm the chosen model's supported modalities, input formats, and size limits.
Output limits and sampling	Verify the supported token-limit and sampling parameter names; do not assume identical ranges or defaults.
Usage and cost	Check returned usage where available and reconcile with FreeBrain usage records; units and rates vary by model.
Timeouts and retries	Set an application timeout, classify retryable errors, and handle partial streaming output explicitly.

Keep a short acceptance set based on real application tasks. For example, a support assistant may need a multi-turn answer and a tool call; a summarizer may need long input and valid structured output. Compare correctness and observed latency using the same inputs and conditions. Do not substitute an advertised context window or a successful “hello” request for those checks.

Switch traffic with a way back

Keep provider URL, key, and model ID in separate server-side configuration. Route a small share of eligible requests to FreeBrain first, and inspect failures, output correctness, and usage before expanding. Preserve the previous configuration so a rollback changes all three settings together. Never fall back by sending one provider's key to another provider's endpoint.

This guide does not supply a universal fallback policy: whether a second generation is acceptable depends on your application's latency, cost, and duplicate-work constraints. Do not automatically retry or fall back after partial streaming output without handling that partial result.

Diagnose a migration that fails

If the cURL example works but the application fails, compare the final URL, authentication, model ID, and request body. Common differences are an extra /v1, a full endpoint entered as a base URL, a stale model name, or an unsupported optional parameter. If both fail, check key permissions, quota, and endpoint availability in the troubleshooting guide.

Use the Chat Completions reference for request fields. The SDK tutorials include executable examples and describe the scope of their automated verification. FreeBrain's model catalog remains the source for currently listed endpoints and pricing; this checklist does not promise equivalent behavior across models.