Documentação

Apontar para o roteador (https://mangabarouter.store/v1) com uma chave mr-… liga limite por chave, cache, fallback entre gateways e o log de tráfego. Apontar direto para o gateway (https://app.mangaba.ia.br/v1) com uma chave sk-… é mais curto, mas nada disso acontece.

Todos os caminhos abaixo foram validados de ponta a ponta contra este roteador, com a receita exata que está em cada seção:

• Minha aplicação usa o SDK da OpenAI — seção 2: mudam duas linhas.
• Uso o SDK da Anthropic — seção 3: mesma ideia, base sem /v1.
• Claude Code no terminal — seção 4: script pronto.
• Codex (CLI da OpenAI) — seção 5: config.toml pronto.
• OpenClaw — seção 6: openclaw.json pronto.
• Hermes (Nous Research) — seção 7: config.yaml pronto.

Regra que vale para todos: os modelos rodam em CPU. Conversa curta volta em segundos; turno de agente com muitas ferramentas leva minutos. Timeout folgado (10 minutos) não é exagero, é requisito.

curl https://mangabarouter.store/v1/chat/completions \
  -H "Authorization: Bearer mr-SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"model":"Mangaba-Nordeste-4B",
       "messages":[{"role":"user","content":"oi"}]}'

A chave sai de Chaves de API, dentro do console. Ela aparece uma única vez — o banco guarda só o hash.

from openai import OpenAI

client = OpenAI(
    base_url="https://mangabarouter.store/v1",   # <- só isto muda
    api_key="mr-SUA_CHAVE",
)

r = client.chat.completions.create(
    model="Mangaba-Nordeste-Coder",
    messages=[{"role": "user", "content": "Olá!"}],
    stream=True,
)

Nenhuma outra linha do seu código muda: o roteador fala o mesmo protocolo, com streaming e tool calling.

# a base NÃO leva /v1: o SDK Anthropic acrescenta /v1/messages sozinho
export ANTHROPIC_BASE_URL=https://mangabarouter.store
export ANTHROPIC_API_KEY=mr-SUA_CHAVE
export ANTHROPIC_MODEL=Mangaba-Nordeste-Coder

# em curl, o caminho completo:
curl https://mangabarouter.store/v1/messages \
  -H "x-api-key: mr-SUA_CHAVE" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"Mangaba-Nordeste-Coder","max_tokens":60,
       "messages":[{"role":"user","content":"Olá!"}]}'

Aceita x-api-key ou Authorization: Bearer, com system no topo, tool use e streaming — os eventos SSE saem no formato Anthropic.

O Claude Code fala Messages API, então funciona aqui — mas exige três ajustes que ninguém adivinha na primeira tentativa. Salve como ~/.local/bin/claude-mangaba e dê chmod +x:

#!/bin/zsh
export ANTHROPIC_BASE_URL="https://mangabarouter.store"
export ANTHROPIC_AUTH_TOKEN="mr-SUA_CHAVE"

# sem os cinco nomes abaixo o cliente manda claude-* e leva 400
export ANTHROPIC_MODEL="Mangaba-Nordeste-Coder"
export ANTHROPIC_DEFAULT_SONNET_MODEL="Mangaba-Nordeste-Coder"
export ANTHROPIC_DEFAULT_OPUS_MODEL="Mangaba-Nordeste-Coder"
export ANTHROPIC_SMALL_FAST_MODEL="Mangaba-Nordeste-4B"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="Mangaba-Nordeste-4B"

export API_TIMEOUT_MS="600000"              # o padrao desiste antes da CPU terminar
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="65536"  # janela real; senao ele presume 200k
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

exec claude --tools "" "$@"                 # so conversa; veja a nota abaixo

Por que --tools "": as 25 ferramentas padrão viajam inteiras em cada turno. Medido em 28/ago: com elas o corpo passa de 70 KB (~18k tokens de entrada) e uma pergunta trivial leva 5min57s; sem elas são 7,6 KB (2.325 tokens) e 54s. Em CPU o gargalo é ler o prompt, não gerar a resposta. Negar ferramenta por permissão não ajuda — a definição continua sendo enviada. Para reativar quando precisar: claude-mangaba --tools "Read,Grep,Bash".

Sobre o tempo: um turno pode passar de um minuto, e por isso o API_TIMEOUT_MS alto importa. O roteador aguenta até 800s por requisição — medido em 28/ago, um prompt de 22,7k tokens de entrada voltou em 427s. Não há mais motivo para apontar direto ao gateway.

A linha [claude-code:unrecognized_model] é só telemetria de nome fora do catálogo dele, e não afeta a chamada. E respostas ficam mais lentas conforme a conversa cresce: cada turno reenvia o histórico inteiro.

O Codex fala a Responses API, que o roteador traduz para o gateway. Crie ~/.codex/config.toml:

model = "Mangaba-Nordeste-Coder"
model_provider = "mangaba"

[model_providers.mangaba]
name = "Mangaba"
base_url = "https://mangabarouter.store/v1"
env_key = "MANGABA_API_KEY"
wire_api = "responses"

export MANGABA_API_KEY=mr-SUA_CHAVE
codex

Use wire_api = "responses": as versões atuais do Codex aposentaram o modo chat. O aviso "Model metadata not found" é inofensivo — o nome não está no catálogo interno dele.

Acrescente ao ~/.openclaw/openclaw.json:

{
  "models": {
    "providers": {
      "mangaba": {
        "baseUrl": "https://mangabarouter.store/v1",
        "apiKey": "mr-SUA_CHAVE",
        "api": "openai-completions",
        "models": [
          { "id": "Mangaba-Nordeste-Coder", "name": "Mangaba Coder",
            "reasoning": false, "input": ["text"],
            "contextWindow": 65536, "maxTokens": 8192 },
          { "id": "Mangaba-Nordeste-4B", "name": "Mangaba 4B",
            "reasoning": false, "input": ["text"],
            "contextWindow": 65536, "maxTokens": 8192 }
        ]
      }
    }
  },
  "agents": {
    "defaults": { "model": { "primary": "mangaba/Mangaba-Nordeste-Coder" } }
  },
  "tools": { "profile": "minimal" }
}

profile: minimal importa: o perfil completo envia 34 definições de ferramenta em cada turno e só a leitura do prompt leva vários minutos em CPU. Se ativar o perfil coding, acrescente "deny": ["cron", "node_inference"] — essas duas usam anyOf no esquema, que o servidor de inferência não compila, e o turno falha com "backend HTTP 400".

Acrescente ao ~/.hermes/config.yaml:

model:
  default: mangaba/Mangaba-Nordeste-Coder
  provider: mangaba
  max_tokens: 2048
providers:
  mangaba:
    api: https://mangabarouter.store/v1
    api_key: mr-SUA_CHAVE

O Hermes dispara chamadas paralelas num mesmo turno; o roteador segura as excedentes em fila por até 2 minutos em vez de recusar — se aparecer 429, é a fila cheia de verdade, e insistir só piora. Teste rápido: hermes -z "oi".

É o tropeço mais comum ao trocar de protocolo, porque cada SDK monta o caminho de um jeito:

• SDK da OpenAI — a base leva /v1: https://mangabarouter.store/v1, e a biblioteca acrescenta /chat/completions.
• SDK da Anthropic — a base não leva /v1: https://mangabarouter.store, porque a biblioteca já acrescenta /v1/messages.

Com /v1 nos dois lugares, a chamada vira /v1/v1/messages e o roteador responde 404 dizendo quais rotas existem — é o sintoma de “não volta nada”.

Uma rota da API da Anthropic não existe aqui: /v1/messages/count_tokens. Clientes que a chamam para estimar tokens recebem 404 e devem seguir sem ela.

O cache devolve em milissegundos o que a inferência em CPU levaria dezenas de segundos — mas só entra em jogo quando repetir a resposta é honesto:

• Pega com temperature: 0 ou sem temperatura, e sem tools.
• Não pega com amostragem ligada (temperature > 0) — ali a variação é o ponto — nem em chamadas com ferramentas, cujo resultado depende do mundo lá fora.
• stream não faz diferença: a mesma pergunta acerta o cache pedindo streaming ou não, e a resposta guardada é reemitida como SSE.

Confira no cabeçalho X-Mangaba-Cache: hit | miss de cada resposta.

São dois limites diferentes, e o erro diz qual:

• Da sua chave, ajustável em Chaves de API (padrão: 60 req/min e 200.000 tokens/hora). A mensagem cita o número configurado.
• Do gateway, fixo em 30 req/min e 60.000 tokens/hora por chave dele. Quando esse estoura, o roteador tenta o próximo gateway da cadeia.

Respeite o cabeçalho Retry-After quando houver e espalhe as chamadas: em CPU, paralelismo não acelera — divide a mesma CPU.

Em Gateways, cadastre mais de um e ordene com as setas. O roteador tenta o primeiro; se ele devolver 5xx, 429 ou não responder, vai para o próximo — e o log mostra quantas tentativas foram feitas e quem atendeu (também no cabeçalho X-Mangaba-Gateway).

Erro 4xx que não seja 429 não aciona fallback: prompt inválido continuaria inválido no próximo gateway.

A sua conta pode ter mais de um provedor de inferência ligado. O roteador olha o campo model e manda a chamada para quem serve aquele modelo — você não muda de URL nem de chave para trocar de provedor.

Para saber quem serve o quê, chame GET https://mangabarouter.store/v1/models: cada entrada traz owned_by com o nome do provedor. A mesma lista aparece agrupada no seletor do Playground, dentro do console.

Quando dois provedores oferecem o mesmo nome de modelo, vale a ordem de prioridade dos gateways. Para fixar um deles, escreva provedor/modelo — poc/Mangaba-gpt-oss-20b, por exemplo. Prefixo que não corresponde a nenhum provedor é ignorado, e o modelo continua valendo.

Nem todo provedor serve toda rota: se um deles não tiver /v1/messages, o roteador tenta o próximo que tiver, em vez de devolver erro.

O roteador recusa qualquer outro nome com 400, antes de sair para a rede: assim ninguém recebe, sem saber, a resposta de um modelo diferente do que pediu.

• Mangaba-Qwen3-Coder-30B-A3Bmangaba-nordesteMangaba-Nordeste-30B - APELIDO LEGADO de Mangaba-Nordeste-Coder: desde 18/ago/2026 os dois nomes atendem no MESMO backend (127.0.0.1:8003), rodando Qwen3-Coder-30B-A3B-Instruct-Q4_K_M. Mantido para nao quebrar clientes antigos; em codigo novo prefira Mangaba-Nordeste-Coder. MoE de 30B totais com ~3,3B ativos por token: qualidade de modelo grande com latencia de modelo pequeno. Otimizado para portugues do Brasil, com foco agentico. QUANDO USAR: e o modelo PADRAO da casa - codigo, laco de agente com ferramentas, tarefas multi-turno, qualquer coisa que exija tool calling confiavel. Nome de modelo desconhecido cai aqui. QUANDO NAO USAR: classificacao ou roteamento de uma linha (o -LFM2.5-1.2B faz o mesmo mais barato) e leitura de imagem (use o -Qwen2.5-VL-7B). POR QUE E RAPIDO: MoE ativa so ~3,3B dos 30B por token, entao lê ~1,9 GB de peso por token em vez dos 17 GB do arquivo - em CPU o que pesa e parametro ATIVO, nao total. ACELERACAO: GWD (esqueleto de tool call semeado) + ngram, com 63-77%% de tokens especulados na 1a tool call. LIMITE: 65.536 tokens por requisicao; acima disso o backend retorna 400 (erro explicito, sem truncar em silencio). Servido pelo gateway. 23,2 tok/s geracao - 54,6 tok/s prompt - 20,5 tok/s tool call.Qwen3-Coder-30B-A3B-Instruct · 30B totais · 3.3B ativos · contexto 65.536 · tool callingtambém atende por: Mangaba-Nordeste-Coder, Mangaba-Nordeste-30B
• Mangaba-Qwen3.5-4Bmangaba-nordesteMangaba-Nordeste-4B - denso compacto (Qwen3.5) para respostas ageis em CPU. QUANDO USAR: perguntas curtas, reformulacao de texto, extracao simples, respostas de baixo custo com tool calling disponivel. E o meio-termo entre o -LFM2.5-1.2B (mais rapido, menos capaz) e o -Coder (mais capaz, MoE). QUANDO NAO USAR: laco agentico longo ou geracao de codigo - use o -Coder, que apesar de ser 30B e MAIS RAPIDO que este por ser MoE. LIMITE: 65.536 tokens; acima disso, 400. Servido pelo gateway. 10,0 tok/s geracao - 15,1 tok/s prompt - 10,3 tok/s tool call.Qwen3.5-4B · 4B · contexto 65.536 · tool callingtambém atende por: Mangaba-Nordeste-4B
• Mangaba-GLM4.5-Air-106Bmangaba-nordesteMangaba-Nordeste-Air - GLM-4.5-Air 106B MoE (12B ativos), o de maior capacidade de raciocinio da casa. QUANDO USAR: problema que exige varios passos de raciocinio encadeado, analise longa, decisao dificil - casos em que a qualidade vale esperar. QUANDO NAO USAR: qualquer coisa trivial. E o MAIS LENTO por larga margem: uma tarefa que o -LFM2.5-1.2B resolve em ~6 s leva ~42 s aqui, e o resultado costuma ser o mesmo em tarefa simples. POR QUE E LENTO: le ~7,1 GB de peso por token (contra 1,9 GB do -Coder); o decode em CPU e limitado por banda de memoria, entao isso e um teto fisico, nao falta de ajuste. ACELERACAO: MTP nativo (camada NextN do GLM-4.5) + ngram. Migrado de Q4 para Q3 em 30/ago/2026: +19%% de geracao e +53%% em tool call. AQUECIMENTO: a 1a chamada apos ociosidade rende ~2,0 tok/s e as seguintes ~3,8 - descarte a primeira ao medir. LIMITE: 65.536 tokens; acima disso, 400. Servido pelo gateway. ~5,6 tok/s geracao - 6,9 tok/s prompt - 4,3 tok/s tool call.GLM-4.5-Air · 106B · contexto 65.536 · tool calling · raciocíniotambém atende por: Mangaba-Nordeste-Air
• Mangaba-Qwen2.5-VL-7Bmangaba-nordesteMangaba-Nordeste-Vision - Qwen2.5-VL 7B, o unico modelo da casa que LE IMAGEM. QUANDO USAR: OCR, leitura de nota fiscal ou documento, descricao de foto, interpretacao de grafico ou print de tela. COMO CHAMAR: `content` vira uma LISTA com um item `text` e um item `image_url` - a url aceita data URI base64 (`data:image/png;base64,...`) ou http. QUANDO NAO USAR: conversa sem imagem (qualquer outro modelo e melhor) e fluxo com ferramentas - NAO faz tool calling. COLD START DE ~49 s: o Ollama descarrega o modelo apos inatividade; a 1a chamada depois de um periodo parado demora quase um minuto e as seguintes ~1,3 s. Se houver usuario esperando, aqueca com uma chamada trivial antes. ATENCAO - TRUNCA EM SILENCIO: janela de 8.192 tokens, e prompt maior NAO da erro; volta 200 com o excesso descartado. Medido: 40.000 tokens enviados viraram `prompt_tokens: 4098`. Confira `usage.prompt_tokens` contra o que voce mandou. Servido pelo gateway. 1,3 s por imagem (quente) - sem tool call.Qwen2.5-VL-7B-Instruct · 7B · contexto 8.192 · visãotambém atende por: Mangaba-Nordeste-Vision
• Mangaba-BGE-M3-568Mmangaba-nordesteMangaba-Nordeste-Embed - BGE-M3 multilingue, o unico modelo de EMBEDDINGS da casa. QUANDO USAR: busca semantica, RAG, deduplicacao, agrupamento por similaridade. COMO CHAMAR: `POST /v1/embeddings` (NAO /v1/chat/completions - este modelo nao conversa e nao gera texto). O campo `input` aceita uma string ou uma lista de strings; mandar em lote e bem mais eficiente que uma chamada por texto. SAIDA: vetores de 1024 dimensoes, um por texto de entrada, na mesma ordem. ATENCAO - TRUNCA EM SILENCIO acima de 8.192 tokens (roda via Ollama): fatie documentos longos em trechos antes de indexar, ou o vetor representara so o comeco do texto. Servido pelo gateway. 10 vetores em 2,45 s - sem geracao.BAAI/bge-m3 · 568M · contexto 8.192também atende por: Mangaba-Nordeste-Embed
• Mangaba-LFM2.5-1.2Bmangaba-nordesteMangaba-Nordeste-Flash - LFM2.5 1.2B, o MAIS RAPIDO da casa. QUANDO USAR: classificacao, roteamento de intencao, extracao de um campo, resposta curta, pre-filtro antes de acionar um modelo caro. E ~7x mais rapido que o -GLM4.5-Air-106B na mesma tarefa trivial. QUANDO NAO USAR: raciocinio de varios passos, codigo nao-trivial ou texto longo - o tamanho cobra o preco; tende a divagar e a ignorar instrucoes de formato rigidas. LIMITE: 32.768 tokens. Servido pelo gateway. 24,9 tok/s geracao - 63,7 tok/s prompt - 25,0 tok/s tool call.LFM2.5-1.2B · 1.2B · contexto 32.768 · tool callingtambém atende por: Mangaba-Nordeste-Flash
• Mangaba-Qwen2.5-7Bmangaba-nordesteMangaba-Qwen2.5-7B - denso de 7B, geracao anterior (Qwen2.5). Alternativa de segunda opiniao quando a resposta do -Qwen3.5-4B parecer fraca: e maior, mas de familia mais antiga, entao nem sempre ganha. QUANDO USAR: comparacao A/B de qualidade, ou fallback se o 4B estiver ocupado. QUANDO NAO USAR: nada que exija tool calling confiavel ou laco agentico - para isso use o -Coder. LIMITE: janela de 8.192 tokens e TRUNCAMENTO SILENCIOSO acima disso (roda via Ollama). Servido pelo gateway.Qwen2.5-7B-Instruct · 7B · contexto 8.192
• Mangaba-Qwen2.5-3Bmangaba-nordesteMangaba-Qwen2.5-3B - o menor denso da casa depois do Flash. QUANDO USAR: tarefa curta e barata em que o -LFM2.5-1.2B erra por ser pequeno demais. QUANDO NAO USAR: como padrao - o -Qwen3.5-4B e de geracao mais nova e costuma responder melhor pelo mesmo custo. ATENCAO: tende a responder em ingles sem instrucao explicita de idioma. LIMITE: 8.192 tokens, com truncamento silencioso acima disso (Ollama). Servido pelo gateway.Qwen2.5-3B-Instruct · 3B · contexto 8.192
• Mangaba-Muse-Glimmer-30Bmangaba-nordesteMuse Glimmer 30B - CABE 18GB, ~12 tok/sMuse-Glimmer-30B · 30B · contexto 131.072 · tool callingtambém atende por: Muse-Glimmer-30B
• Mangaba-Ling-Flashmangaba-nordesteLing Flash 124B CABE 62GBLing Flash 124B · 124B · contexto 262.144 · tool callingtambém atende por: Ling-Flash
• Mangaba-Ling-Tinymangaba-nordesteLing Tiny CABE 4.5GB Ideal CPULing Tiny 7.9B · 7.9B · contexto 262.144 · tool callingtambém atende por: Ling-tiny
• Mangaba-Nemotron-Nanomangaba-nordesteNemotron Nano 30B CABE 16GB RecomendadoNemotron Nano 30B · 30B · contexto 1.048.576 · tool callingtambém atende por: Nemotron-Nano
• Mangaba-Nemotron-Supermangaba-nordesteNemotron Super 120B CABE 60GB limiteNemotron Super 120B · 120B · contexto 1.048.576 · tool callingtambém atende por: Nemotron-Super
• Mangaba-fgemma-270mkleosO menor e mais rápido da base: classificação, extração de campo e respostas curtas em alto volume. Não é modelo de conversa longa.Gemma 3 270M (Google), denso
• Mangaba-gpt-oss-20bkleosAgente com raciocínio e tool calling. Pensa antes de responder, então precisa de max_tokens generoso — com orçamento curto o texto visível volta vazio.gpt-oss-20b (OpenAI, Apache 2.0), MoE
• Mangaba-ministral-14bkleosMeio-termo entre velocidade e qualidade para texto em português. Serve para resumo, reescrita e respostas de suporte.Família Mistral (o gateway não informa a variante exata)
• Mangaba-mistral-small-24bkleosO mais capaz do Kleos para redação e análise mais longa; em troca, o mais lento dos modelos daquele provedor.Mistral Small 24B, denso
• Mangaba-qwen3-0.6bkleosO menor Qwen da base: roteamento de mensagens e classificação binária em volume altíssimo. Para qualquer texto que uma pessoa vá ler, use um modelo maior.Qwen3 0.6B, denso
• Mangaba-qwen3-1.7bkleosRaciocínio em modelo pequeno: rápido, mas gasta parte do orçamento pensando antes de escrever. Use max_tokens alto.Qwen3 1.7B, denso
• Mangaba-qwen3-coder-30bkleosEspecialista em programação e tool calling. Servido por mais de um provedor — fixe com kleos/ ou poc/ para escolher qual.Qwen3-Coder-30B-A3B (MoE, ~3,3B ativos)
• Mangaba-voz-ptbrkleosTexto vira fala em português brasileiro, pela rota /v1/audio/speech. Vozes Kokoro: pf_dora, pm_alex e pm_santa (campo voice). Devolve WAV.Kokoro TTS
• Mangaba-audio-whisperkleosTranscrição de áudio (Whisper), pela rota /v1/audio/transcriptions. Atenção: hoje o servidor devolve o texto traduzido para o inglês (modo translate) — em correção.Whisper (o gateway não informa a variante)
• Mangaba-qwen3-30bpocMelhor em portugues do catalogo. Base: Qwen3-30B-A3B-Instruct-2507 (Alibaba, Apache 2.0), MoE de 30B totais e 3B ativos, Q4_K_M. Contexto nativo de 262k tokens. ~33 tok/s.o gateway não informa a base
• Mangaba-gpt-oss-120bpocAgente principal. Base: gpt-oss-120b (OpenAI, Apache 2.0), MoE de 117B parametros totais e 5,1B ativos, quantizacao MXFP4 nativa. Tool calling forte e raciocinio ajustavel. ~20 tok/s nesta maquina.o gateway não informa a base
• Mangaba-granite-4-smallpocOpcao de licenca comercial livre. Base: Granite 4.0 H Small (IBM, Apache 2.0), MoE hibrido Mamba de 32B totais e 9B ativos, Q4_K_M. Treinado com foco em function calling. ~11 tok/s — mais lento porque tem mais parametros ativos.o gateway não informa a base
• Mangaba-embedpocVetores para busca semântica e RAG, pela rota /v1/embeddings. Não conversa: transforma texto em números para comparar significado. 1024 dimensões.Modelo de embeddings, 1024 dimensões (o gateway não informa a base)
• Mangaba-rerankpocReordena resultados de busca por relevância à pergunta, pela rota /v1/rerank. Usado depois do embedding, para pôr no topo o trecho que de fato responde.Reranker de busca (o gateway não informa a base)
• Mangaba-audiopocTranscrição de áudio para texto, pela rota /v1/audio/transcriptions. Não atende chat.Transcrição de fala (o gateway não informa a base)
• Mangaba-audio-hqpocTranscrição de áudio em qualidade alta, pela rota /v1/audio/transcriptions — mais precisa e mais lenta que a Mangaba-audio.STT (o gateway não informa a base)
• Mangaba-vozpocTexto vira fala, pela rota /v1/audio/speech. Vozes: faber, cadu e jeff (campo voice). Devolve WAV pronto para tocar.TTS (o gateway não informa a base)

Os metadados acima vêm do próprio gateway que serve cada modelo, e mudam quando ele muda. A velocidade medida de cada um está em /modelos, calculada sobre as chamadas reais. O contexto é a janela por requisição — prompt maior retorna 400.