Referência da API

Introdução

A API da Labrai dá acesso aos modelos KPH por HTTP. O formato segue o de Chat Completions da OpenAI: bibliotecas compatíveis funcionam trocando o endereço base e a chave.

Documentação provisória. A API ainda não está aberta; endpoints, nomes de modelos e limites podem mudar.

Endereço base: https://api.labrai.com.br/v1 · HTTPS e JSON (UTF-8).

Início rápido

Gere uma chave na plataforma em breve.
Exporte: export LABRAI_API_KEY="..."
Faça a primeira chamada:

curl https://api.labrai.com.br/v1/chat/completions \
  -H "Authorization: Bearer $LABRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kph-chat",
    "messages": [
      {"role": "system", "content": "Responda em português do Brasil."},
      {"role": "user", "content": "Explique o que é um token em uma frase."}
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.labrai.com.br/v1",
    api_key=os.environ["LABRAI_API_KEY"],
)

resp = client.chat.completions.create(
    model="kph-chat",
    messages=[{"role": "user", "content": "Olá! Quem é você?"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.labrai.com.br/v1",
  apiKey: process.env.LABRAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "kph-chat",
  messages: [{ role: "user", content: "Olá! Quem é você?" }],
});
console.log(resp.choices[0].message.content);

Autenticação

Envie a chave no cabeçalho Authorization de todas as requisições. Não exponha a chave no navegador nem em apps públicos.

Authorization: Bearer $LABRAI_API_KEY

Criar resposta

POST /v1/chat/completions

Gera a próxima mensagem de uma conversa.

Parâmetro	Descrição
`model` obrigatório string	ID do modelo, ex.: `kph-chat` (provisório).
`messages` obrigatório array	Mensagens da conversa: objetos `{role, content}` com role `system`, `user` ou `assistant`.
`temperature` number	De 0 a 2. Valores maiores deixam a resposta mais variada.
`top_p` number	Amostragem por núcleo, de 0 a 1.
`max_tokens` integer	Máximo de tokens gerados na resposta.
`stream` boolean	Se `true`, envia a resposta em partes (Server-Sent Events).
`stop` string \| array	Sequências que encerram a geração.

Objeto de resposta

200 OK

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1763050000,
  "model": "kph-chat",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Um token é um pedaço de texto..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 21, "completion_tokens": 18, "total_tokens": 39}
}

Streaming

Com "stream": true, a resposta chega em eventos data: com choices[0].delta.content, terminando em data: [DONE].

text/event-stream

data: {"choices":[{"delta":{"content":"Um"}}]}

data: {"choices":[{"delta":{"content":" token"}}]}

data: [DONE]

Listar modelos

GET /v1/models

Lista os modelos disponíveis para a sua chave.

curl https://api.labrai.com.br/v1/models \
  -H "Authorization: Bearer $LABRAI_API_KEY"

for m in client.models.list():
    print(m.id)

const list = await client.models.list();
for (const m of list.data) console.log(m.id);

200 OK

{"object": "list", "data": [{"id": "kph-chat", "object": "model", "owned_by": "labrai"}]}

Erros

Erros retornam o código HTTP e um corpo {"error": {"type", "message", "code"}}.

HTTP	type	Quando
400	`invalid_request_error`	Corpo inválido ou parâmetro ausente.
401	`authentication_error`	Chave ausente, inválida ou revogada.
403	`permission_error`	A chave não tem acesso a este modelo.
404	`not_found_error`	Modelo ou rota inexistente.
429	`rate_limit_error`	Limite de requisições ou de créditos atingido.
500	`api_error`	Erro interno. Tente de novo com espera exponencial.
503	`overloaded_error`	Capacidade temporariamente esgotada.

Limites de taxa provisório

Nível	Requisições / min	Tokens / min
Inicial	a definir	a definir
Empresas	sob consulta	sob consulta

Cabeçalhos x-ratelimit-remaining-requests e x-ratelimit-remaining-tokens: em breve.

Versões

A versão da API faz parte do caminho (/v1). Mudanças incompatíveis virão numa nova versão, com aviso prévio.