Source: https://ailoot.ai/docs/pt-pt/how-it-works/
Canonical: https://ailoot.ai/docs/pt-pt/how-it-works/
Language: pt-pt

[Introdução](https://ailoot.ai/docs/pt-pt/) 

# Como funciona

[Markdown](https://ailoot.ai/docs/pt-pt/how-it-works/index.md)

O que acontece ao pedido entre a sua aplicação e o modelo.

Envia um pedido à API Ailoot tal como o enviaria diretamente para OpenAI, Anthropic ou Google. O Ailoot verifica a chave e o saldo, transmite o pedido ao modelo, devolve a resposta no mesmo formato e debita pelo consumo efetivo.

<em>01</em><strong>Pedido</strong>O seu cliente envia um pedido para api.ailoot.ai com a chave sk-…

<em>02</em><strong>Validação e reserva</strong>Chave, limites, saldo. É reservado um valor durante a preparação da resposta.

<em>03</em><strong>Modelo</strong>O modelo responde e a resposta é devolvida no seu formato.

<em>04</em><strong>Débito</strong>Um único débito pelos tokens efetivos; o restante valor reservado é libertado.

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#formats)Uma chave — três formatos

O formato é determinado pelo caminho do pedido, e não pelo modelo. Pode chamar o mesmo modelo Claude através de OpenAI Chat, OpenAI Responses ou Anthropic Messages — a resposta terá o formato do caminho utilizado.

| Formato | Caminho | Quem o utiliza |
| --- | --- | --- |
| OpenAI Chat Completions | `/v1/chat/completions` | OpenAI SDK, a maioria dos chats e editores, n8n, LangChain |
| OpenAI Responses | `/v1/responses` | Codex CLI, OpenAI Agents SDK, versões recentes dos SDK |
| Anthropic Messages | `/v1/messages` | Claude Code, Anthropic SDK, Zed, Cline |
| Gemini | `/v1beta/models/{model}:generateContent` | Gemini CLI, Google GenAI SDK |

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#money)Dinheiro: reserva e um único débito

- Antes de enviar um novo pedido de texto, o Ailoot reserva o custo estimado da entrada e de uma resposta típica, tendo em conta o limite (`max_tokens`) e as condições do modelo em concreto. Se a reserva não couber no saldo disponível ou no limite da chave, o limite enviado só pode ser reduzido se o modelo e o método efetivamente o respeitarem, sem nunca ficar abaixo de 256 tokens nem do mínimo de resposta definido. Para imagens, vídeo e áudio gerados, mantém-se a reserva integral do custo do resultado.
- Após a resposta — um único débito pelo consumo efetivo. A reserva não utilizada é devolvida imediatamente ao saldo.
- Se a resposta custar mais do que a reserva, a diferença é retirada do saldo disponível. O saldo nunca fica negativo.
- Se o dinheiro não chegar sequer para a reserva mínima, o pedido não é enviado: recebe um erro 402 claro, sem qualquer débito.
- Um erro sem resultado não é cobrado.

Os detalhes e um exemplo de cálculo estão na página [Reserva e débito](https://ailoot.ai/docs/pt-pt/billing/reserve/).

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#errors)Erros com Request ID

Cada resposta recebe um identificador de pedido: no cabeçalho `X-Request-ID` e no texto do erro. Os erros chegam em JSON no formato que chamou, pelo que os SDK os reconhecem corretamente. Se algo correr mal, envie o Request ID ao [suporte](https://ailoot.ai/docs/pt-pt/support/) — assim, encontramos o pedido num minuto.

401 Unauthorized

```json
{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}
```

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#streaming)Fluxo e tempos limite

As respostas em fluxo (`stream: true`) são transmitidas como Server-Sent Events. O Ailoot entrega a resposta de texto paga após o cálculo do custo. Por isso, com `stream: true` o formato continua a ser em fluxo (SSE), mas o texto chega num único bloco quando o modelo termina, e não palavra a palavra. Se a resposta demorar mais de cerca de 15 segundos, os fluxos Chat Completions, Responses e Messages começam por linhas de serviço `: ping` (aproximadamente a cada 10 segundos), seguidas da linha `: ailoot-charged-usd …` com o valor debitado e dos dados propriamente ditos. Os SDK ignoram essas linhas.

No formato Gemini, não existem linhas de serviço: a resposta `:streamGenerateContent` chega integralmente após o cálculo. Defina uma margem no tempo limite do cliente para modelos de raciocínio: vários minutos é normal.

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#headers)Cabeçalhos da resposta

`X-Request-ID` é incluído em todas as respostas. O Ailoot acrescenta os restantes cabeçalhos às respostas de texto pagas:

| Cabeçalho | Conteúdo |
| --- | --- |
| `X-Request-ID` | Identificador do pedido — é solicitado pelo suporte |
| `X-Ailoot-Charged-USD` | Valor debitado por este pedido, em dólares |
| `X-Ailoot-Output-Tokens` | Número de tokens de resposta cobrados |
| `X-Ailoot-Max-Tokens-Capped` | Limite ao qual a resposta foi reduzida porque o saldo não chegava para a reserva total |
| `X-Ailoot-Notice-Code`, `X-Ailoot-Notice` | Explicação se a resposta parar no limite de comprimento |

Se o fluxo já tiver começado com linhas de serviço, estes dados chegam numa linha de comentário antes dos dados, em vez de num cabeçalho.

## [](https://ailoot.ai/docs/pt-pt/how-it-works/#cache)Cache de prompts

Se o modelo suportar cache, reenviar um prefixo longo (instrução de sistema, documentos) pode ser mais barato. Os preços de leitura e escrita da cache estão na ficha do modelo no [catálogo](https://ailoot.ai/models/pt-pt/). A ocorrência de um acerto na cache depende do programador do modelo; o Ailoot não o garante.

Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.[Contactar o suporte](mailto:support@ailoot.ai)

## Ailoot · A empresa e a sua carteira de projetos





A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.





A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.





A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.