Documentação Caravela Code
A Caravela Code é um modelo para editores de código com IA — Cursor, OpenCode, Zed, Codex e equivalentes. O editor liga-se como fornecedor OpenAI-compatible e usa a Caravela nos fluxos de chat, edição e agentes.
| URL base | https://api.caravela.chat/api/code/v1 |
| Modelo | caravela |
| Chave API | O mesmo token da API Caravela — crie no perfil |
Para uma visão geral do produto, consulte a página Caravela Code.
O token completo só é mostrado uma vez quando o cria. No editor, cole-o no campo de API key (não o partilhe em repositórios públicos).
Ligar o editor
- Crie um token
amalia_live_…. - No editor, adicione um fornecedor OpenAI-compatible (ou «modelo personalizado»).
- Preencha a URL base, a chave API e o modelo
caravela. - Seleccione
caravelano selector de modelos e comece a programar.
Procure no editor opções como OpenAI Compatible, Custom provider ou Override OpenAI Base URL. A URL base termina em /v1 — o editor acrescenta /chat/completions sozinho.
Guias oficiais por editor
Cada ferramenta tem o seu ecrã de configuração. Use os valores acima e siga o guia do editor:
| Editor | Configuração de modelos personalizados |
|---|---|
| Cursor | Chaves API e modelos — em Settings → Models, active Override OpenAI Base URL e cole a URL base |
| OpenCode | Custom provider |
| Zed | OpenAI-Compatible Endpoints |
| Codex | Custom model providers |
| Continue | OpenAI API compatible providers |
| Cline | OpenAI Compatible |
| Roo Code | OpenAI Compatible |
| Kilo Code | OpenAI Compatible |
| Aider | OpenAI compatible APIs |
| Crush | Custom Providers |
| Goose | LLM Providers |
Outros editores e agentes funcionam da mesma forma, desde que aceitem um endpoint OpenAI-compatible.
Autenticação
O editor envia o token no cabeçalho Authorization:
Authorization: Bearer amalia_live_<seu_token>
- O token é criado e eliminado por si no perfil.
- O consumo é faturado por utilização e partilhado entre a API Caravela e a Caravela Code.
Preços
Consulte os preços por milhão de tokens — entrada, entrada em cache e saída — na secção de preços da página da API.
Sem mensalidade nem compromisso. A Caravela Code partilha a faturação por utilização com a API Caravela.
Faturação e limites de uso
A API é faturada por utilização, calculada por milhão de tokens (entrada, entrada em cache e saída), partilhada entre a API Caravela e a Caravela Code.
- Sem mensalidade: paga apenas pelos tokens que consumir.
- Para começar, tem de registar um método de pagamento no perfil.
- Acompanhe a utilização e a faturação no perfil.
Sem faturação ativa — quando a conta não tem faturação por uso ativa, os novos pedidos são rejeitados com 429.
{
"error": {
"message": "API token limit reached.",
"type": "rate_limit_error",
"param": null,
"code": "api_token_limit_reached",
"billing_required": true
}
}
Erros
Se o editor mostrar uma falha de ligação, estes códigos HTTP são os mais comuns:
| HTTP | Código | Situação |
|---|---|---|
400 | invalid_parameter | Campo inválido ou em falta |
400 | model_not_found | Modelo diferente de caravela |
401 | invalid_api_key | Token ausente, inválido ou conta não encontrada |
404 | not_found | Rota inexistente |
405 | method_not_allowed | Método HTTP não suportado |
429 | api_token_limit_reached | Limite de tokens da conta atingido |
502 | upstream_error | Falha ao contactar o motor upstream |
504 | upstream_timeout | Tempo limite do motor upstream |
Suporte
Dúvidas ou pedidos de aumento do limite: info@userquest.io
Para a API completa com ferramentas do servidor e modelo Amália, consulte a documentação da API.