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
| Modelo | Descrição |
|---|---|
amalia | Modelo português experimental. |
caravela | Inteligê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
| Campo | Obrigatório | Descrição |
|---|---|---|
model | Sim | "amalia" ou "caravela" |
messages | Sim | Histórico da conversa no formato OpenAI |
stream | Não | false (omissão) para JSON completo; true para SSE |
thinking | Não | false por omissão. Com true, o modelo pensa mais antes de responder. |
library_id | Não | UUID da biblioteca RAG privada. Define a biblioteca usada por search_client_rag. Não altera tools nem tool_choice. |
citation_protocol | Nã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_set | Não | Bloco 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_plan | Não | Blob 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_format | Não | Saída estruturada (Structured Outputs): {"type": "json_schema", "json_schema": {...}} — ver Saída estruturada. |
tools | Não | Lista de ferramentas: type: "custom" (servidor) ou type: "function" (cliente). Não misturar os dois tipos no mesmo pedido. |
tool_choice | Não | Formato 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
| Pedido | Comportamento |
|---|---|
(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 custom | Apenas as ferramentas do servidor indicadas |
tools só com function | Tools do cliente e todas as do servidor (com library_id, inclui search_client_rag) |
tools com custom e function | 400 — não é permitido misturar |
tools: [] | Sem ferramentas (resposta directa) |
tool_choice: "none" | Sem ferramentas, mesmo que tools esteja presente |
search_client_rag sem library_id | 400 — 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ório | Descrição |
|---|---|---|
name | Sim | Nome do formato (a-z, A-Z, 0-9, _ e -, até 64 caracteres) |
schema | Sim | JSON Schema que o modelo deve seguir |
description | Não | Instrução para o modelo sobre quando e como usar o formato |
strict | Não | Ativa adesão estrita ao schema quando true |
Comportamento:
- Disponível nos modelos
amaliaecaravela, comstream: trueoustream: false. - O
contentda 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"devolve400invalid_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.
| Campo | Descrição |
|---|---|
schema_version | Sempre 2 |
sources | Lista de fontes citadas |
sources[].index | Número que corresponde a [1], [2], … no texto |
sources[].title | Título legível da fonte |
sources[].source_label | Nome curto da origem (ex.: «Pesquisa web», «Diário da República») |
sources[].kind | Tipo de fonte — ex.: web, dre, portuguese_law, rag, google_places |
sources[].url | URL pública, quando existir |
sources[].article | Artigo ou diploma, quando aplicável |
sources[].page | Página, quando aplicável |
sources[].section | Secção, quando aplicável |
sources[].version | Versã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, semamalia_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
- Criar uma biblioteca com
create_new_library. - Indexar documentos com
index_new_document(upload ou URL HTTPS). - Consultar
process_statusaté o documento ficarready. - Enviar perguntas em
/api/v1/chat/completionscomlibrary_idno pedido. - O modelo usa a ferramenta
search_client_ragpara 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
| Estado | Descrição |
|---|---|
queued | Aguarda processamento |
processing | Indexação em curso |
ready | Disponível para pesquisa |
failed | Falha na indexação — consulte error_code |
deleting | Remoçã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
| HTTP | Código | Situação |
|---|---|---|
400 | invalid_parameter | Campo inválido (ex.: library_id em falta) |
400 | invalid_document | Ficheiro inválido, formato não suportado ou URL inaceitável |
404 | library_not_found | Biblioteca inexistente ou de outra conta |
404 | process_not_found | Processo de indexação não encontrado |
409 | library_already_exists | Nome de biblioteca duplicado |
409 | library_not_ready | Biblioteca sem documentos ready para pesquisa |
409 | process_busy | Processo de indexação já em execução |
503 | index_queue_unavailable | Falha 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
| HTTP | Código | Situação |
|---|---|---|
400 | invalid_parameter | Campo 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) |
400 | unsupported_tool | Tool do servidor desconhecida, ou nome de function a colidir com uma tool interna |
401 | invalid_api_key | Token ausente, inválido ou conta não encontrada |
404 | library_not_found | library_id inexistente ou de outro utilizador |
404 | not_found | Rota inexistente |
405 | method_not_allowed | Método HTTP não suportado (ex.: GET em /chat/completions) |
409 | library_not_ready | A biblioteca não tem documentos indexados prontos para pesquisa |
429 | api_token_limit_reached | Limite de tokens da conta atingido |
502 | upstream_error | Falha 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.