API compatível com OpenAI e Ollama

Integre a Lucy aos seus projetos.

A API da Lucy expõe endpoints no formato OpenAI (base /v1) e no formato Ollama nativo (/api/*), para que qualquer cliente que fale essas linguagens — SDKs, LiteLLM, Open WebUI, Cursor, SillyTavern — funcione com poucas linhas de configuração. O código-fonte é proprietário; esta documentação cobre todos os endpoints públicos.

Base URL https://chat.opentty.fun

Autenticação

Todas as chamadas de geração exigem uma chave de API. A listagem de modelos é pública por padrão.

Obtendo uma chave

Entre na conta, abra o painel (seção Chaves API) e crie uma chave. Você também pode pedir a um administrador. Limite: até 10 chaves ativas por usuário.

As chaves têm o formato lucy_<prefixo>_<id> e são mostradas apenas uma vez no momento da criação — guarde-a com segurança.

Enviando a chave

Você pode autenticar de três formas (a primeira é a recomendada):

curl https://chat.opentty.fun/v1/models \
  -H "Authorization: Bearer lucy_XXXX_YYYY"

curl https://chat.opentty.fun/v1/models \
  -H "X-API-Key: lucy_XXXX_YYYY"

# Legado: a chave também é aceita na URL (?key= / ?token= / ?api_key=).
# Prefira o header Authorization — chave na URL entra em histórico,
# Referer e logs de proxy. Nos logs da Lucy ela sai mascarada.
curl "https://chat.opentty.fun/v1/models?key=lucy_XXXX_YYYY"

Permissões das chaves

Permissão	Libera
chat	Chat, completions, embeddings e endpoints /api/* (padrão)
files	Cloud: upload, download, editor de arquivos
notes	Notas
investigator	Modo detetive, busca e fetch da web
worker	Autentica o worker de download/e-mail (não dá acesso às APIs)
device	Conecta o Lucy Device Bridge (acesso ao seu PC pelo chat)

Segurança: nunca exponha a chave em código client-side ou em repositórios públicos. Trate-a como senha.

Acesso administrativo: rotas /api/admin/* nunca aceitam chave de API — exigem sessão de navegador de um administrador.

Dispositivo (PC)

O Lucy Device Bridge dá à Lucy acesso ao seu computador pelo chat: informações do sistema, shell e arquivos. O script abre uma conexão de saída — nenhuma porta precisa ser aberta no roteador — e o terminal local apenas mostra o que o modelo executou. Não existe controle pelo terminal: tudo acontece em chat, pela ferramenta control_device.

1. Baixe o script

É um único arquivo Python, sem dependências (a biblioteca padrão basta; psutil é opcional e melhora memória/processos). O mesmo arquivo também roda o worker do Lucy Downloader com --download — não existe mais um script separado. Você também encontra o download e o status da conexão em Configurações → MCP (engrenagem no chat).

Baixar lucy.py

2. Autentique e rode

Na primeira execução, o script pergunta usuário/e-mail e senha e guarda apenas a API key de dispositivo em ~/.config/lucy/device.json. A senha nunca é salva.

python3 lucy.py --url https://chat.opentty.fun

Você também pode criar uma chave em Chaves API marcando a permissão device e usá-la direto (sem login interativo):

python3 lucy.py --url https://chat.opentty.fun --api-key lucy_XXXX_YYYY

Quer ajudar o Lucy Downloader também? O mesmo arquivo sobe o worker de download junto com o bridge:

python3 lucy.py --download

Deixe o terminal aberto. Quando quiser controlar, abra o chat e peça — por exemplo: “veja o que está consumindo CPU no meu PC” ou “liste os arquivos da minha pasta Downloads”.

Opções úteis

Opção	Efeito
--read-only	Desativa escrita, exclusão e movimentação de arquivos
--no-shell	Desativa shell e listagem de processos
--root /caminho	Restringe as ferramentas de arquivo a essa pasta
--name "Meu PC"	Nome exibido no chat e no status
--login	Força novo login com usuário/e-mail + senha
--logout	Apaga a credencial salva no PC
--insecure	Não valida TLS (somente para testes locais)
--download	Também sobe o worker do Lucy Downloader (yt-dlp) junto com o bridge
--download-only	Roda só o worker de download, sem acesso ao PC

Atenção: o Device Bridge dá à Lucy o mesmo acesso que o seu usuário tem no PC. Rode apenas em uma máquina confiável, use --read-only ou --root quando não precisar de acesso total e revogue a chave em Chaves API se o PC for perdido ou compartilhado. Comandos destrutivos só são executados depois de confirmação no chat.

O servidor precisa de um worker Gunicorn (padrão da Lucy) para o WebSocket do dispositivo e o chat caírem no mesmo processo.

Modelos

A Lucy roda sobre um único cérebro próprio. O modelo canônico é lucy:latest — todos os aliases abaixo resolvem para ele, então qualquer cliente funciona.

Alias	Descrição
lucy:latest	Resolve para o modelo canônico `lucy:latest`
lucy	Resolve para o modelo canônico `lucy:latest`
lucy:7b	Resolve para o modelo canônico `lucy:latest`
lucy-chat	Resolve para o modelo canônico `lucy:latest`
*	Qualquer id começando com `lucy` — ou mesmo um id desconhecido — roda como `lucy:latest`

Sempre envie "model": "lucy:latest" ou qualquer alias para máxima compatibilidade.

Endpoints

Clique em um endpoint para ver os parâmetros e exemplos.

POST /v1/chat/completions Chat — formato OpenAI

Gera uma resposta de chat. Suporta messages (formato OpenAI) ou prompt. A última mensagem user é usada como instrução; system vira instrução de sistema. Nota: a Lucy ainda não usa histórico multi-turn da API — cada chamada é independente.

Parâmetros do corpo

modelstringID do modelo (qualquer alias). Padrão: lucy:latest

messagesarrayobrigatório*Mensagens com role system/user/assistant

promptstringAlternativa ao messages

streambooleanSSE streaming. Padrão: false

temperaturenumberAceito por compatibilidade (ignorado)

max_tokensintegerAceito por compatibilidade (ignorado)

curl https://chat.opentty.fun/v1/chat/completions \
  -H "Authorization: Bearer lucy_XXXX_YYYY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lucy:latest",
    "messages": [
      {"role": "system", "content": "Você é a Lucy, uma companheira carinhosa."},
      {"role": "user", "content": "Oi, Lucy! Como foi seu dia?"}
    ],
    "stream": false
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://chat.opentty.fun/v1",   # troque pelo seu host
    api_key="lucy_XXXX_YYYY",
)

resp = client.chat.completions.create(
    model="lucy:latest",
    messages=[
        {"role": "system", "content": "Você é a Lucy, uma companheira carinhosa."},
        {"role": "user", "content": "Oi, Lucy! Como foi seu dia?"},
    ],
)
print(resp.choices[0].message.content)

const client = new OpenAI({
  baseURL: "https://chat.opentty.fun/v1",   // troque pelo seu host
  apiKey: "lucy_XXXX_YYYY",
});

const resp = await client.chat.completions.create({
  model: "lucy:latest",
  messages: [
    { role: "system", content: "Você é a Lucy, uma companheira carinhosa." },
    { role: "user", content: "Oi, Lucy! Como foi seu dia?" },
  ],
});
console.log(resp.choices[0].message.content);

Resposta

{
  "id": "chatcmpl-1a2b3c4d5e6f",
  "object": "chat.completion",
  "created": 1754670000,
  "model": "lucy:latest",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Meu dia foi ótimo!" },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 6,
    "total_tokens": 24
  },
  "system_fingerprint": "lucy",
  "lucy": {
    "thoughts": "...",
    "sentiment": "happy",
    "response_type": "normal",
    "energy": 82
  }
}

O campo lucy (pensamentos, sentimento, energia) é incluído por padrão e pode ser desligado com API_EXPOSE_METRICS=0. Clientes OpenAI ignoram campos desconhecidos sem quebrar.

POST /v1/completions Texto — legacy

Completions de texto no formato legacy da OpenAI. Envie o texto em prompt (ou input) e receba text na resposta.

promptstringobrigatórioTexto de entrada

modelstringAlias do modelo

streambooleanStreaming. Padrão: false

curl https://chat.opentty.fun/v1/completions \
  -H "Authorization: Bearer lucy_XXXX_YYYY" \
  -H "Content-Type: application/json" \
  -d '{"model": "lucy:latest", "prompt": "Conte uma piada curta."}'

GET /v1/models Listar modelos (público)

Lista os modelos disponíveis. Público por padrão (PUBLIC_MODEL_LIST=1); com 0, exige chave. Também aceita /v1/models/<id> para detalhe de um modelo.

curl https://chat.opentty.fun/v1/models

{
  "object": "list",
  "data": [
    { "id": "lucy:latest", "object": "model", "created": 1704067200, "owned_by": "lucy" }
  ]
}

POST /v1/embeddings Embeddings (stub determinístico)

Gera embeddings pseudo-determinísticos (hash → vetor normalizado) com dimensão fixa (EMBEDDING_DIM, padrão 384). Servem apenas para não quebrar clientes que exigem o endpoint — não têm significado semântico real.

inputstring | arrayobrigatórioTexto ou lista de textos

modelstringPadrão: text-embedding-3-small

curl https://chat.opentty.fun/v1/embeddings \
  -H "Authorization: Bearer lucy_XXXX_YYYY" \
  -H "Content-Type: application/json" \
  -d '{"input": ["olá mundo", "lucy é incrível"]}'

Compatibilidade Ollama (`/api/*`)

A mesma API responde no formato nativo do Ollama. Configure OLLAMA_HOST para este host e a maioria dos apps funciona direto.

POST /api/chat Chat Ollama

Chat no formato Ollama. Padrão de streaming: true (NDJSON).

curl https://chat.opentty.fun/api/chat \
  -H "Authorization: Bearer lucy_XXXX_YYYY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lucy:latest",
    "stream": false,
    "messages": [{"role": "user", "content": "Qual é o seu nome?"}]
  }'

POST /api/generate Geração Ollama

Geração de texto no formato Ollama. Campo de resposta: response.

curl https://chat.opentty.fun/api/generate \
  -H "Authorization: Bearer lucy_XXXX_YYYY" \
  -H "Content-Type: application/json" \
  -d '{"model": "lucy:latest", "stream": false, "prompt": "Olá!"}'

GET /api/tags Listar modelos Ollama

curl https://chat.opentty.fun/api/tags

Também disponíveis para probes: GET /api/version, GET /api/ps e POST /api/show.

Streaming

Passe "stream": true nos endpoints OpenAI para receber eventos SSE (data: ...), terminando em data: [DONE].

from openai import OpenAI

client = OpenAI(base_url="https://chat.opentty.fun/v1", api_key="lucy_XXXX_YYYY")

stream = client.chat.completions.create(
    model="lucy:latest",
    messages=[{"role": "user", "content": "Conte uma história."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Nos endpoints Ollama o streaming é NDJSON (uma linha JSON por pedaço), padrão true.

Erros

Erros seguem o padrão da OpenAI: código HTTP + corpo com error.

Status	Significado
400	Requisição inválida (ex.: sem mensagem/prompt)
401	Chave ausente, inválida ou expirada
403	Chave sem a permissão necessária
429	Rate limit excedido
500	Erro interno

{
  "error": {
    "message": "Invalid API key. Use Authorization: Bearer  or X-API-Key.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Rate limit

Os endpoints de geração são limitados a 60 requisições por minuto por cliente. Ao exceder, você recebe 429.

A Lucy é um cérebro local com custo real de processamento. Se precisar de volume maior, fale com o administrador.

Spec OpenAPI

Exportamos a especificação OpenAPI 3.0.3 em JSON para você importar em ferramentas como Swagger UI, Postman e Insomnia.

Spec: https://chat.opentty.fun/openapi.json
Postman: Import → link → cole a URL acima.
Swagger UI: informe a URL da spec no campo de input.
Insomnia: Import → From URL.

Os exemplos desta página usam o host atual: https://chat.opentty.fun.

Integre a Lucy aos seus projetos.

Autenticação

Obtendo uma chave

Enviando a chave

Permissões das chaves

Dispositivo (PC)

1. Baixe o script

2. Autentique e rode

Opções úteis

Modelos

Endpoints

Parâmetros do corpo

Resposta

Compatibilidade Ollama (/api/*)

Streaming

Erros

Rate limit

Spec OpenAPI

Compatibilidade Ollama (`/api/*`)