← Voltar à página da API

Documentação da API

A API da Caravela é compatível com o formato OpenAI Chat Completions. Consulte a documentação oficial da OpenAI para a especificação completa dos campos de pedido e resposta. Esta página documenta apenas as diferenças.

OpenAI SDK: defina base_url como https://api.caravela.chat/api/v1 e api_key com o seu token Amália.

Os endpoints anteriores https://api.iaamalia.com/api/v1 e https://iaamalia.com/api/v1 continuam funcionais para clientes existentes.

Para obter acesso, crie o seu token API no perfil. O token completo só é mostrado uma vez.


Autenticação

Todos os endpoints exigem um token fixo no cabeçalho Authorization.

Authorization: Bearer amalia_live_<seu_token>
  • O token é criado e eliminado por si no perfil.
  • Guarde o token em segurança — não partilhe em repositórios públicos nem no frontend.
  • Ao eliminar um token, o acesso é revogado imediatamente.

Endpoints

GET /api/v1/health

Verifica se a API está disponível.

{ "status": "ok" }

GET /api/v1/models

Lista os modelos disponíveis, em formato compatível com OpenAI.

{
  "object": "list",
  "data": [
    { "id": "amalia", "object": "model", "created": 1755000000, "owned_by": "ia-amalia" },
    { "id": "caravela", "object": "model", "created": 1755000000, "owned_by": "ia-amalia" }
  ]
}

O campo created é um timestamp Unix gerado no momento do pedido.

POST /api/v1/chat/completions

Endpoint compatível com OpenAI Chat Completions, com as seguintes diferenças:

Streaming e não-streaming. O campo stream é opcional e tem o valor por omissão false. Com stream: true a resposta é SSE (chat.completion.chunk).

Ferramentas do servidor. Com type: "custom", a seleção e execução acontecem no servidor. O cliente recebe apenas a resposta final — não vê as tool_calls internas.

Ferramentas do cliente. Com type: "function" (formato OpenAI), o modelo pode pedir essas tools e a API devolve finish_reason: "tool_calls". O cliente executa-as, reenvia messages com role: "tool", e a API continua (incluindo tools do servidor, se o modelo as pedir).


Modelos

ModeloDescrição
amaliaModelo português experimental.
caravelaInteligência de topo, para trabalho profissional.

Ambos podem usar as ferramentas do servidor e do cliente.


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.


Campos do pedido

CampoObrigatórioDescrição
modelSim"amalia" ou "caravela"
messagesSimHistórico da conversa no formato OpenAI
streamNãofalse (omissão) para JSON completo; true para SSE
thinkingNãofalse por omissão. Com true, o modelo pensa mais antes de responder.
library_idNãoUUID da biblioteca RAG privada. Define a biblioteca usada por search_client_rag. Não altera tools nem tool_choice.
citation_protocolNão"legacy" por omissão. Use "v2" para citações com metadados estruturados — ver Citações e fontes. Ignorado (tratado como "legacy") quando response_format está presente.
ine_working_setNãoBloco compacto de resoluções INE (ecoado na resposta). Reenvie-o nos follow-ups se o histórico não incluir tool. A resposta JSON e o último chunk SSE (finish_reason: "stop") podem incluir ine_working_set e ine_pindica_gets na raiz.
task_work_planNãoBlob opaco do WorkPlan em curso (ecoado na resposta). Reenvie-o no turno seguinte para o executor retomar o mesmo task_id. Fechar o browser perde o estado em v1.
response_formatNãoSaída estruturada (Structured Outputs): {"type": "json_schema", "json_schema": {...}} — ver Saída estruturada.
toolsNãoLista de ferramentas: type: "custom" (servidor) ou type: "function" (cliente). Não misturar os dois tipos no mesmo pedido.
tool_choiceNãoFormato OpenAI ChatCompletionToolChoiceOptionParam: "auto", "none", "required", {"type":"function","function":{"name":"…"}}, {"type":"custom","custom":{"name":"…"}}, ou {"type":"allowed_tools","allowed_tools":{…}}

Imagens

Serve para processar imagens: faturas, talões, formulários, tabelas, páginas fotografadas, fotografias, posters ou screenshots. O servidor extrai o conteúdo visual (texto de documentos e/ou uma descrição da cena) e o modelo (caravela ou amalia) responde a partir dessa extracção.

Não existe um campo extra (image, image_base64) nem um endpoint de visão. messages[].content continua a poder ser uma string, como até agora, ou um array multimodal OpenAI com partes text e image_url.

A imagem pode ir em data:image/...;base64 ou numa URL HTTPS pública. Formatos: JPEG, PNG, WebP e GIF, até 4 MB por imagem e 3 imagens por turno. A URL tem de ser alcançável pela internet (não localhost nem redes privadas). PDFs não são aceites neste fluxo.

Base64:

{
  "model": "caravela",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Qual é o total desta fatura?"},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
    ]
  }]
}

URL HTTPS:

{
  "model": "caravela",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Extrai os artigos e o total desta fatura."},
      {"type": "image_url", "image_url": {"url": "https://empresa.pt/fatura.jpg"}}
    ]
  }]
}

A leitura corre antes da resposta, mesmo com tool_choice: "none". O modelo principal não recebe os pixels. O formato da resposta da API não muda.

Documentos (PDF, TXT, Markdown, DOCX e texto UTF-8)

Serve para processar ficheiros de texto: PDF com camada de texto, .txt, Markdown, .docx, e aliases UTF-8 (.json, .csv, .tsv, .xml, .html, .yaml/.yml, .toml, .log). O servidor extrai o texto e o modelo responde a partir dessa extracção. JSON/YAML não são validados; HTML chega com as tags. Não é RAG (não indexa bibliotecas) e não é visão (não lê pixels; um PDF só com scan é recusado). Spreadsheets (.xlsx) e slides (.pptx) não são aceites.

messages[].content pode incluir partes file em paralelo com text e image_url:

{
  "model": "caravela",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Resume este contrato."},
      {
        "type": "file",
        "file": {
          "filename": "contrato.pdf",
          "file_data": "data:application/pdf;base64,..."
        }
      }
    ]
  }]
}

URL HTTPS pública no mesmo objecto (file_url em vez de file_data). A URL tem de ser alcançável pela internet (não localhost nem redes privadas).

Limites: 10 MB por ficheiro, PDF até 100 páginas, 300 000 caracteres extraídos no total do turno, 400 000 caracteres de documentos na conversa (ficheiros já lidos mais o novo), até 3 ficheiros por turno. PDFs encriptados são recusados. As páginas digitalizadas (sem camada de texto) são lidas por um modelo de visão; as páginas digitais mantêm o seu texto. Um PDF em que nenhuma página digitalizada pôde ser lida devolve 400 pdf_scan_unreadable; um PDF sem texto, nem lido pelo modelo de visão, devolve 400 pdf_no_extractable_text.

Não se trunca em silêncio. Códigos de erro: unsupported_file_type, file_too_large, too_many_files, pdf_too_many_pages, document_too_long, conversation_documents_too_long, pdf_encrypted, pdf_no_extractable_text, pdf_scan_unreadable, invalid_file, invalid_file_url.

A leitura corre antes da resposta, mesmo com tool_choice: "none". O modelo principal não recebe os bytes do ficheiro.

Comportamento das ferramentas

PedidoComportamento
(padrão, sem tools)Todas as ferramentas do servidor. Com library_id, inclui search_client_rag.
tool_choice: "auto"O modelo decide se chama ferramentas (omissão quando há tools)
tool_choice: "required"O modelo tem de chamar pelo menos uma ferramenta
tool_choice: {"type":"function","function":{"name":"…"}}Força uma tool function
tool_choice: {"type":"custom","custom":{"name":"…"}}Força uma tool interna do servidor
tool_choice: {"type":"allowed_tools",…}Restringe o modelo ao conjunto indicado (mode: "auto" ou "required")
tools só com customApenas as ferramentas do servidor indicadas
tools só com functionTools do cliente e todas as do servidor (com library_id, inclui search_client_rag)
tools com custom e function400 — não é permitido misturar
tools: []Sem ferramentas (resposta directa)
tool_choice: "none"Sem ferramentas, mesmo que tools esteja presente
search_client_rag sem library_id400 — na lista tools ou em tool_choice

Cada ferramenta do servidor usa o formato Amália com type: "custom":

{ "type": "custom", "custom": { "name": "search_web" } }

Ferramentas do cliente usam o formato OpenAI type: "function":

{
  "type": "function",
  "function": {
    "name": "my_lookup",
    "description": "Consulta o CRM do cliente",
    "parameters": { "type": "object", "properties": { "id": { "type": "string" } } }
  }
}

Nomes de function que coincidam com tools do servidor devolvem 400 com código unsupported_tool. Nomes custom desconhecidos devolvem 400 com código invalid_parameter (validação Pydantic) ou unsupported_tool.

Ferramentas disponíveis

search_carris, search_ciberduvidas, search_client_rag, search_competencias_chave, search_bep, search_dgal, search_dgeg, search_dgert, search_dges_bolsa, search_dre, search_ecb, search_ers, search_ersar, search_eurlex, get_eurostat, search_eurostat, search_fullenrich, search_google_places, search_gov_servicos, search_idealista, search_ine, search_infoescolas, search_infomatricula, search_infraestruturas_portugal, search_lisboa_porto_dados, search_mais_transparencia, search_metro_transportes, search_numeros_justica, search_openprocurements, search_pordata, search_portal_base, search_portuguese_law, search_priberam, search_qualifica, search_sns_transparencia, search_ted, search_tribunal_constitucional, search_turismo_portugal, search_web, summarize_website

search_client_rag só está disponível quando o pedido inclui library_id de uma biblioteca com documentos indexados. Sem library_id não entra no conjunto por omissão; pedi-la em tools ou em tool_choice devolve 400.

Saída estruturada (Structured Outputs)

Garante que a resposta do modelo é JSON válido conforme um schema que define. O campo response_format segue o formato Structured Outputs da OpenAI:

{
  "type": "json_schema",
  "json_schema": {
    "name": "crime_stats",
    "description": "Estatísticas de criminalidade por distrito.",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "distrito": { "type": "string" },
        "crimes": { "type": "integer" }
      },
      "required": ["distrito", "crimes"],
      "additionalProperties": false
    }
  }
}
Campo (json_schema)ObrigatórioDescrição
nameSimNome do formato (a-z, A-Z, 0-9, _ e -, até 64 caracteres)
schemaSimJSON Schema que o modelo deve seguir
descriptionNãoInstrução para o modelo sobre quando e como usar o formato
strictNãoAtiva adesão estrita ao schema quando true

Comportamento:

  • Disponível nos modelos amalia e caravela, com stream: true ou stream: false.
  • O content da resposta (ou os deltas SSE) é JSON puro — sem citações nem texto adicional.
  • As ferramentas continuam a funcionar: o servidor pesquisa e executa as tools e só o JSON final é gerado de acordo com o schema.
  • Só é aceite o tipo json_schema. Pedir "type": "json_object" ou "type": "text" devolve 400 invalid_parameter.
  • Com response_format, citation_protocol é tratado como "legacy" (a resposta não leva marcadores de citação).

Exemplo com curl:

curl -sS https://api.caravela.chat/api/v1/chat/completions \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amalia",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "crime_stats",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "distrito": {"type": "string"},
            "crimes": {"type": "integer"}
          },
          "required": ["distrito", "crimes"],
          "additionalProperties": false
        }
      }
    },
    "messages": [
      {"role": "user", "content": "Quantos crimes houve em Lisboa no ano passado?"}
    ]
  }'

Com o SDK OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.caravela.chat/api/v1",
    api_key="amalia_live_SEU_TOKEN",
)

completion = client.chat.completions.create(
    model="caravela",
    messages=[{"role": "user", "content": "Resume em JSON o que foi decidido na reunião."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "meeting_summary",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "resumo": {"type": "string"},
                    "decisoes": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["resumo", "decisoes"],
                "additionalProperties": False,
            },
        },
    },
)

print(completion.choices[0].message.content)

Se o provider do modelo rejeitar o response_format (schema inválido ou não suportado), a API devolve 400 invalid_parameter com param: "response_format"; falhas do provider devolvem 502 upstream_error. Isto aplica-se a pedidos stream: false e a streams sem ferramentas ativas (tool_choice: "none" ou tools: []); num stream já aberto com ferramentas, uma rejeição do provider pode interromper a resposta.


Citações e fontes

Quando o modelo usa ferramentas de pesquisa (por exemplo search_web, search_dre ou search_client_rag), pode citar as fontes na resposta. Com citation_protocol: "v2", recebe o texto com referências numeradas e metadados estruturados para apresentar links, títulos e detalhes da fonte na sua aplicação.

Funciona com amalia e caravela, com ou sem stream.

Activar

Inclua "citation_protocol": "v2" no corpo JSON do pedido a POST /api/v1/chat/completions. Se omitir o campo, o comportamento por omissão é "legacy" (sem amalia_citations).

{
  "model": "caravela",
  "citation_protocol": "v2",
  "messages": [
    { "role": "user", "content": "Quem é o atual presidente da República?" }
  ]
}
curl -sS https://api.caravela.chat/api/v1/chat/completions \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caravela",
    "citation_protocol": "v2",
    "messages": [
      {"role": "user", "content": "Quem é o atual presidente da República?"}
    ]
  }'

Com o SDK OpenAI, envie o campo através de extra_body:

completion = client.chat.completions.create(
    model="caravela",
    messages=[{"role": "user", "content": "Quem é o atual presidente da República?"}],
    extra_body={"citation_protocol": "v2"},
)

Formato da resposta

Texto (choices[0].message.content). As citações aparecem como índices [1], [2], … pela ordem em que surgem no texto. Exemplo:

Marcelo Rebelo de Sousa é o atual Presidente da República [1].

Metadados (amalia_citations). Objecto na raiz da resposta (fora de choices) com as fontes citadas. Só inclui fontes que aparecem no texto — não lista resultados de pesquisa não referenciados.

CampoDescrição
schema_versionSempre 2
sourcesLista de fontes citadas
sources[].indexNúmero que corresponde a [1], [2], … no texto
sources[].titleTítulo legível da fonte
sources[].source_labelNome curto da origem (ex.: «Pesquisa web», «Diário da República»)
sources[].kindTipo de fonte — ex.: web, dre, portuguese_law, rag, google_places
sources[].urlURL pública, quando existir
sources[].articleArtigo ou diploma, quando aplicável
sources[].pagePágina, quando aplicável
sources[].sectionSecção, quando aplicável
sources[].versionVersão ou data da fonte, quando aplicável

Exemplo de resposta (sem streaming):

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "caravela",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Marcelo Rebelo de Sousa é o atual Presidente da República [1]."
      },
      "finish_reason": "stop"
    }
  ],
  "amalia_citations": {
    "schema_version": 2,
    "sources": [
      {
        "index": 1,
        "title": "Presidente da República",
        "source_label": "Pesquisa web",
        "kind": "web",
        "url": "https://www.presidencia.pt/…"
      }
    ]
  }
}

Streaming

Com stream: true, o texto chega em chunks OpenAI normais (choices[0].delta.content). O objecto amalia_citations vem no último chunk — o que tem finish_reason: "stop" — antes de data: [DONE]. No mesmo chunk, se o turno usou o INE (ou reenviou ine_working_set), vêm ine_working_set e ine_pindica_gets. Se um run_analysis ainda estiver em curso, o mesmo chunk inclui task_work_plan para o cliente reenviar.

Se usar o SDK OpenAI em modo streaming, leia amalia_citations desse chunk final (por exemplo através de model_extra ou do JSON bruto do evento SSE).

Notas

  • Citações dependem de ferramentas que devolvem fontes consultáveis. Com tool_choice: "none" ou sem pesquisa relevante, a resposta pode não ter referências.
  • Referências inválidas ou sem correspondência numa fonte recuperada são removidas do texto.
  • O protocolo "legacy" mantém o comportamento anterior, sem amalia_citations.

Bibliotecas RAG

A API de bibliotecas RAG permite criar bibliotecas privadas de documentos, indexar ficheiros ou URLs e usar esse conhecimento nas respostas da Amália. Os documentos ficam isolados por conta e são pesquisados apenas quando o pedido de chat inclui o library_id da biblioteca.

URL base: https://api.caravela.chat/api/rag/v1

Usa o mesmo token amalia_live_... da API Caravela. Para uma visão geral do produto, consulte a página RAG para empresas.

Fluxo típico

  1. Criar uma biblioteca com create_new_library.
  2. Indexar documentos com index_new_document (upload ou URL HTTPS).
  3. Consultar process_status até o documento ficar ready.
  4. Enviar perguntas em /api/v1/chat/completions com library_id no pedido.
  5. O modelo usa a ferramenta search_client_rag para consultar os documentos indexados.

Formatos aceites

TXT, Markdown (.md), PDF e DOCX. Limite de 50 MB por documento. PDFs digitalizados sem texto extraível precisam de OCR antes da indexação.

Estados do documento

EstadoDescrição
queuedAguarda processamento
processingIndexação em curso
readyDisponível para pesquisa
failedFalha na indexação — consulte error_code
deletingRemoção em curso

Endpoints de gestão

Todos exigem Authorization: Bearer amalia_live_<seu_token>.

POST /api/rag/v1/create_new_library

Cria uma biblioteca privada.

POST /api/rag/v1/create_new_library
Content-Type: application/json

{"library_name":"Apoio ao cliente"}

Resposta 201:

{
  "object": "rag.library",
  "library_id": "<uuid>",
  "library_name": "Apoio ao cliente"
}

GET /api/rag/v1/list_libraries

Lista as bibliotecas da conta.

{
  "object": "list",
  "data": [
    {
      "object": "rag.library",
      "library_id": "<uuid>",
      "library_name": "Apoio ao cliente",
      "created_at": "2026-01-15T10:00:00+00:00",
      "updated_at": "2026-01-15T10:00:00+00:00"
    }
  ]
}

DELETE /api/rag/v1/delete_library

Elimina uma biblioteca e todos os documentos associados.

DELETE /api/rag/v1/delete_library
Content-Type: application/json

{"library_name":"Apoio ao cliente"}

POST /api/rag/v1/index_new_document

Indexa um ficheiro por upload ou por URL HTTPS pública.

Upload (multipart/form-data):

POST /api/rag/v1/index_new_document
Content-Type: multipart/form-data

library_id=<uuid>
parser_type=generic
file=@manual.pdf

URL (application/json):

{
  "library_id": "<uuid>",
  "file_url": "https://example.com/manual.md",
  "parser_type": "generic"
}

Só são aceites URLs HTTPS que resolvam para endereços públicos. O download é limitado a 50 MB. parser_type é obrigatório por documento. Use generic para documentos gerais ou legislation para exigir parsing por artigo, epígrafe e hierarquia jurídica. O parser jurídico não faz fallback automático para o parser genérico.

Resposta 202:

{
  "object": "rag.index_process",
  "library_id": "<uuid>",
  "document_id": "<uuid>",
  "process_id": "<uuid>",
  "status": "queued"
}

GET /api/rag/v1/process_status

Consulta o estado de um processo de indexação.

GET /api/rag/v1/process_status?library_id=<uuid>&process_id=<uuid>

GET /api/rag/v1/list_documents

Lista os documentos de uma biblioteca.

GET /api/rag/v1/list_documents?library_id=<uuid>

DELETE /api/rag/v1/delete_document

Remove um documento indexado.

DELETE /api/rag/v1/delete_document
Content-Type: application/json

{"library_id":"<uuid>","document_id":"<uuid>"}

Usar no chat

Envie library_id como campo adicional no pedido de chat. Com o SDK OpenAI, use extra_body:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.caravela.chat/api/v1",
    api_key="amalia_live_SEU_TOKEN",
)

stream = client.chat.completions.create(
    model="amalia",
    messages=[{"role": "user", "content": "Qual é o prazo de devolução?"}],
    stream=True,
    extra_body={"library_id": "<uuid-da-biblioteca>"},
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="")

Com library_id, a ferramenta search_client_rag junta-se às outras do servidor. Sem library_id, essa ferramenta não está disponível — pedir-la em tools ou tool_choice devolve 400.

O servidor valida que a biblioteca pertence à conta do token e pesquisa apenas documentos com estado ready. Perguntas, excertos e respostas neste modo não são enviados para PostHog nem para logs de debug.

Exemplo completo com curl

# 1. Criar biblioteca
curl -X POST "https://api.caravela.chat/api/rag/v1/create_new_library" \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"library_name":"Manuais internos"}'

# 2. Indexar PDF
curl -X POST "https://api.caravela.chat/api/rag/v1/index_new_document" \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -F "library_id=<uuid>" \
  -F "parser_type=generic" \
  -F "file=@manual.pdf"

# 3. Consultar processo
curl "https://api.caravela.chat/api/rag/v1/process_status?library_id=<uuid>&process_id=<uuid>" \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN"

# 4. Perguntar com a biblioteca
curl -N -X POST "https://api.caravela.chat/api/v1/chat/completions" \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amalia",
    "messages": [{"role": "user", "content": "Qual é o prazo de devolução?"}],
    "stream": true,
    "library_id": "<uuid>"
  }'

Erros relacionados com RAG

HTTPCódigoSituação
400invalid_parameterCampo inválido (ex.: library_id em falta)
400invalid_documentFicheiro inválido, formato não suportado ou URL inaceitável
404library_not_foundBiblioteca inexistente ou de outra conta
404process_not_foundProcesso de indexação não encontrado
409library_already_existsNome de biblioteca duplicado
409library_not_readyBiblioteca sem documentos ready para pesquisa
409process_busyProcesso de indexação já em execução
503index_queue_unavailableFalha ao enfileirar indexação

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). Para começar a fazer pedidos, tem de registar um método de pagamento no perfil.

  • Sem mensalidade: paga apenas pelos tokens que consumir.
  • O consumo inclui todas as chamadas internas ao modelo (seleção de ferramentas, análises auxiliares e resposta final).
  • Pode acompanhar 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 e billing_required: true.

{
  "error": {
    "message": "API token limit reached.",
    "type": "rate_limit_error",
    "param": null,
    "code": "api_token_limit_reached",
    "billing_required": true
  }
}

Erros específicos da Amália

HTTPCódigoSituação
400invalid_parameterCampo inválido ou em falta (ex.: model inválido, misturar custom e function em tools, search_client_rag sem library_id, response_format sem name/schema ou com type diferente de json_schema)
400unsupported_toolTool do servidor desconhecida, ou nome de function a colidir com uma tool interna
401invalid_api_keyToken ausente, inválido ou conta não encontrada
404library_not_foundlibrary_id inexistente ou de outro utilizador
404not_foundRota inexistente
405method_not_allowedMétodo HTTP não suportado (ex.: GET em /chat/completions)
409library_not_readyA biblioteca não tem documentos indexados prontos para pesquisa
429api_token_limit_reachedLimite de tokens da conta atingido
502upstream_errorFalha do provider do modelo (ex.: response_format rejeitado)

Exemplos

Resposta directa (sem ferramentas)

curl -N -X POST "https://api.caravela.chat/api/v1/chat/completions" \
  -H "Authorization: Bearer amalia_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amalia",
    "messages": [
      { "role": "user", "content": "Olá, quem és?" }
    ],
    "tool_choice": "none",
    "stream": true
  }'

Sem tool_choice: "none", o servidor activa todas as ferramentas por defeito.

Python (SDK da OpenAI)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.caravela.chat/api/v1",
    api_key="amalia_live_SEU_TOKEN",
)

stream = client.chat.completions.create(
    model="caravela",
    messages=[{"role": "user", "content": "Olá, quem és?"}],
    stream=True,
    extra_body={"thinking": True},
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="")

Resposta completa (sem streaming):

completion = client.chat.completions.create(
    model="amalia",
    messages=[{"role": "user", "content": "Olá, quem és?"}],
    stream=False,
)

print(completion.choices[0].message.content)

Por omissão, o servidor usa todas as ferramentas. Use tool_choice="none" para desactivá-las.

O campo thinking é uma extensão opcional ao formato OpenAI. Com o SDK oficial, envie-o através de extra_body, como no exemplo. Use true quando quiser que o modelo dedique mais raciocínio à resposta; omita-o ou use false para o modo normal. A resposta mantém o formato OpenAI Chat Completions.

Seleção automática de ferramentas

stream = client.chat.completions.create(
    model="amalia",
    messages=[
        {"role": "user", "content": "Que apoios estão abertos para PME?"}
    ],
    tool_choice="auto",
    stream=True,
)

O servidor escolhe entre todas as ferramentas disponíveis e devolve a resposta final.

Ferramentas específicas

stream = client.chat.completions.create(
    model="caravela",
    messages=[
        {"role": "user", "content": "Quem é o atual primeiro-ministro?"}
    ],
    tools=[
        {"type": "custom", "custom": {"name": "search_web"}}
    ],
    stream=True,
)

Apenas search_web fica disponível para este pedido.

Ferramentas do cliente (type: "function")

completion = client.chat.completions.create(
    model="caravela",
    messages=[{"role": "user", "content": "Qual o estado da encomenda 42?"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "lookup_order",
                "description": "Consulta o estado de uma encomenda",
                "parameters": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string"}},
                    "required": ["order_id"],
                },
            },
        }
    ],
)

message = completion.choices[0].message
if completion.choices[0].finish_reason == "tool_calls":
    # Executar as tools do cliente e continuar o histórico OpenAI
    messages = [
        {"role": "user", "content": "Qual o estado da encomenda 42?"},
        message,
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": '{"status":"enviada"}',
        },
    ]
    completion = client.chat.completions.create(
        model="caravela",
        messages=messages,
        tools=[
            {
                "type": "function",
                "function": {
                    "name": "lookup_order",
                    "description": "Consulta o estado de uma encomenda",
                    "parameters": {
                        "type": "object",
                        "properties": {"order_id": {"type": "string"}},
                        "required": ["order_id"],
                    },
                },
            }
        ],
    )

Não misture type: "function" com type: "custom" no mesmo pedido. Com só function, o servidor activa também todas as tools internas (invisíveis); estas podem correr no pedido de continuação, depois dos resultados do cliente.

Listar modelos

curl "https://api.caravela.chat/api/v1/models" \
  -H "Authorization: Bearer amalia_live_<seu_token>"

Caravela Code

Endpoint dedicado a programação e agentes de IA. Documentação completa na página Caravela Code e referência técnica.

OpenAI SDK: base_url="https://api.caravela.chat/api/code/v1" e api_key com o token Amália.


Suporte

Dúvidas ou pedidos de aumento do limite: info@userquest.io

Para uma visão geral do produto API, consulte a página da API.