Braino AI — Developer API

Base URL: https://braino.tech/api/v1 · versioned; new versions never break existing clients.

Authentication

Every request needs a Braino API key in the Authorization header:

Authorization: Bearer braino_live_xxxxxxxxxxxx

Keys are per-application, scoped (ai:text, ai:embedding, ai:image), revocable, and rate-limited. Test keys use the braino_test_ prefix. Keys are stored only as a hash — the full value is shown once at creation.

Endpoints

Method	Path	Scope
GET	/api/v1/models	any
POST	/api/v1/chat/completions	ai:text
POST	/api/v1/embeddings	ai:embedding
POST	/api/v1/images/generations	ai:image
GET	/api/v1/usage	any
GET	/health · /ready	public

Chat completions

curl https://braino.tech/api/v1/chat/completions \
  -H "Authorization: Bearer braino_live_..." -H "Content-Type: application/json" \
  -d '{"model":"braino-text-sm","messages":[{"role":"user","content":"Hello!"}],"temperature":0.7,"max_tokens":256}'

Response is OpenAI-shaped: choices[0].message.content, plus usage and x_braino_node (which compute node served it). Model names are stable Braino names — you never address a physical node.

Embeddings

curl https://braino.tech/api/v1/embeddings \
  -H "Authorization: Bearer braino_live_..." -H "Content-Type: application/json" \
  -d '{"model":"braino-embed","input":"a friendly dolphin"}'

Images

Returns 501 not_available until a GPU compute node is provisioned. Braino AI never returns a fake image.

Models

Name	Capability	License
braino-text-sm	text (fast, CPU)	Apache-2.0
braino-text-lg	text (quality, GPU)	Apache-2.0
braino-embed	embeddings (768-d)	Apache-2.0

Errors

Errors are JSON: {"error":{"message":"...","type":"..."}}. Types: authentication_error (401), permission_error (403), rate_limit_error (429), not_available (501), server_error (5xx).

Rate limits

Per API key, per minute (default 60). Exceeding returns 429. Contact an admin to raise a key's limit.