← Voltar à página Caravela Code

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 basehttps://api.caravela.chat/api/code/v1
Modelocaravela
Chave APIO 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

  1. Crie um token amalia_live_….
  2. No editor, adicione um fornecedor OpenAI-compatible (ou «modelo personalizado»).
  3. Preencha a URL base, a chave API e o modelo caravela.
  4. Seleccione caravela no 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:

EditorConfiguração de modelos personalizados
CursorChaves API e modelos — em Settings → Models, active Override OpenAI Base URL e cole a URL base
OpenCodeCustom provider
ZedOpenAI-Compatible Endpoints
CodexCustom model providers
ContinueOpenAI API compatible providers
ClineOpenAI Compatible
Roo CodeOpenAI Compatible
Kilo CodeOpenAI Compatible
AiderOpenAI compatible APIs
CrushCustom Providers
GooseLLM 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:

HTTPCódigoSituação
400invalid_parameterCampo inválido ou em falta
400model_not_foundModelo diferente de caravela
401invalid_api_keyToken ausente, inválido ou conta não encontrada
404not_foundRota inexistente
405method_not_allowedMétodo HTTP não suportado
429api_token_limit_reachedLimite de tokens da conta atingido
502upstream_errorFalha ao contactar o motor upstream
504upstream_timeoutTempo 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.