Documentation

Documentação da API

Usando um assistente de IA? Passe para ele o /llms.txt. Ele cobre cadastro, recarga e chamadas de ponta a ponta.

A API Lacia é compatível com a API Chat Completions da OpenAI. Código existente com o SDK da OpenAI só precisa de novos base_url e api_key.

Início rápido

Crie uma conta e adicione saldo no painel.
Crie uma chave em Painel → API Keys. Ela aparece só uma vez, então guarde-a.
Defina a variável de ambiente LACIA_API_KEY e rode qualquer exemplo abaixo.

Autenticação

Todos os endpoints /v1 exigem a chave de API no cabeçalho da requisição:

Authorization: Bearer sk-lacia-xxxxxxxxxxxxxxxx

Nunca exponha sua chave em código front-end, repositórios públicos ou apps cliente. Se vazar, exclua-a no painel imediatamente e crie outra.

Base URL e modelos

Base URL

https://lacia.app/v1

Protocolo

HTTPS, JSON, UTF-8

Compatibilidade

OpenAI Chat Completions (com streaming)

Chat Completions

POST/v1/chat/completions

Parâmetros da requisição

Parâmetro	Tipo	Descrição
`model`	string, obrigatório	`lacia-creator` ou `lacia-researcher`
`messages`	array, obrigatório	Mensagens da conversa; cada uma tem `role` (system / user / assistant) e `content`
`stream`	boolean	Retorna a resposta em streaming via SSE. Padrão: false
`max_tokens`	integer	Máximo de tokens de saída. Padrão: 32K; valores acima do limite do modelo (384K) são reduzidos ao limite
`temperature`	number	0–2; quanto maior, mais variado
`top_p`	number	Amostragem nucleus, 0–1
`stop`	string \| array	Sequências de parada
`presence_penalty` / `frequency_penalty`	number	-2–2; reduz repetições

Exemplo de requisição

{
  "model": "lacia-creator",
  "messages": [
    {"role": "system", "content": "Você é um narrador de humor sombrio."},
    {"role": "user", "content": "Um parágrafo de abertura, com menos de 200 palavras."}
  ],
  "temperature": 0.9,
  "max_tokens": 800
}

Exemplo de resposta

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "lacia-creator",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 42, "completion_tokens": 186, "total_tokens": 228}
}

Streaming

Defina "stream": true e a resposta vem como text/event-stream. Cada evento tem o formato data: {...}, o texto incremental fica em choices[0].delta.content e o stream termina com data: [DONE]. O último evento de dados tem o array choices vazio e traz o usage.

Modo de raciocínio

O raciocínio de cada modo é fixo. Campos como thinking, reasoning_effort e chat_template_kwargs na requisição são ignorados.

Modelo	Raciocínio	Descrição
`lacia-creator`	Desativado	Responde direto, com primeiro token mais rápido; ideal para escrita e conversa
`lacia-researcher`	Ativado	Raciocina antes de responder; ideal para análises complexas e código

O Researcher retorna o raciocínio em message.reasoning_content (delta.reasoning_content no streaming); a resposta final continua em content. O raciocínio conta em completion_tokens, é cobrado pelo preço de saída e consome parte do limite de max_tokens. Em conversas de vários turnos, basta devolver o content em messages; se a requisição tiver tools, reenvie cada reasoning_content retornado, sem alterar, na mensagem assistant correspondente, senão a API retorna 400.

Uso

Toda resposta bem-sucedida inclui o campo usage:

prompt_tokens

Tokens de entrada, cobrados pelo preço de entrada

completion_tokens

Tokens de saída, cobrados pelo preço de saída

total_tokens

Soma dos dois

No painel, Uso agrega por dia e por modelo, e Logs de requisições mostra tokens, custo, latência e status de cada requisição. Em casos raros o serviço do modelo não retorna usage; então estimamos pela contagem de caracteres e marcamos o registro como “estimado”.

Listar modelos

GET/v1/models

curl https://lacia.app/v1/models -H "Authorization: Bearer $LACIA_API_KEY"

Códigos de erro

As respostas de erro seguem o formato da OpenAI:

{"error": {"message": "Insufficient balance. Please top up in the dashboard.", "type": "insufficient_quota", "code": "insufficient_balance"}}

HTTP	code	Causa e solução
400	`invalid_json` / `invalid_messages`	Corpo da requisição inválido; verifique o JSON e messages
400	`context_length_exceeded`	Entrada longa demais; reduza o contexto
401	`missing_api_key` / `invalid_api_key`	Chave de API ausente ou inválida
402	`insufficient_balance`	Saldo insuficiente; recarregue e tente de novo
403	`spend_limit_exceeded`	Você atingiu seu teto de gasto mensal
404	`model_not_found`	Parâmetro model inválido
429	`rate_limit_exceeded`	Requisições demais por minuto; tente de novo com backoff exponencial
502	`upstream_error`	Erro no serviço do modelo; pode tentar de novo, sem cobrança
503	`upstream_overloaded`	Serviço do modelo ocupado; tente em instantes, sem cobrança

Limites de taxa e cotas

Os limites de taxa valem por chave de API e por modo, conforme a tabela abaixo. Fale com a gente se precisar de mais.
Defina um teto de gasto mensal no painel. Ao atingi-lo, as requisições retornam 403 até o mês seguinte.
Defina um alerta de saldo baixo e o painel avisará quando o saldo ficar abaixo dele.