Source: https://docs.aivax.net/pt-br/docs/inference/chat-completions/concepts.html

# Conceitos de inferência

A AIVAX expõe uma API `chat/completions` compatível com OpenAI, com parâmetros adicionais da AIVAX. As adições são opcionais e foram projetadas para suportar gateways, RAG (Recuperação Aumentada de Geração), ferramentas integradas, respostas estruturadas, pré-processamento multimodal, roteamento de provedores e metadados de faturamento.

Estas páginas cobrem o contrato de solicitação. Utilize um [Gateway de IA](https://docs.aivax.net/pt-br/docs/inference/ai-gateways/concepts.md) quando a mesma configuração precisar ser reutilizada ou gerenciada centralmente.

## Chamada direta ou gateway

Utilize uma chamada direta para tarefas simples, testes, rotinas internas e integrações onde o aplicativo controla o modelo, o prompt, as ferramentas e o contexto para cada solicitação.

Utilize um Gateway de IA quando o comportamento precisar ser estável, auditável e reutilizável. Os gateways são melhores para assistentes de suporte, chatbots, agentes RAG, ferramentas permanentes, trabalhadores, habilidades e configurações compartilhadas por vários clientes. Consulte [Inferência com Gateways de IA](https://docs.aivax.net/pt-br/docs/inference/chat-completions/ai-gateways.md) para entender como um gateway altera uma solicitação.

## Como uma solicitação é executada

Uma única solicitação pode envolver várias gerações de modelos. A AIVAX prepara o contexto, chama o modelo, executa quaisquer ferramentas do lado do servidor solicitadas pelo modelo, chama o modelo novamente com os resultados delas e repete até que o modelo produza uma resposta final ou solicite uma ferramenta que seu cliente deve executar.

1. **Preparar.** A AIVAX resolve o modelo ou gateway, adiciona instruções do gateway e documentos recuperados, restaura o [contexto do lado do servidor](https://docs.aivax.net/pt-br/docs/inference/chat-completions/server-side-context.md) das rodadas anteriores, aplica [pré-processamento](https://docs.aivax.net/pt-br/docs/inference/chat-completions/multimodal-pre-processing.md) e moderação, e ajusta a conversa à janela de contexto.
2. **Gerar.** O provedor selecionado gera raciocínio, texto ou chamadas de ferramenta; consulte [Roteamento](https://docs.aivax.net/pt-br/docs/inference/routing/setup-routing.md) para saber como o provedor é escolhido.
3. **Executar ferramentas do lado do servidor.** [Ferramentas integradas](https://docs.aivax.net/pt-br/docs/inference/chat-completions/built-in-tools.md), [ferramentas MCP e funções de protocolo](https://docs.aivax.net/pt-br/docs/inference/chat-completions/mcp-and-protocol-functions.md) são executadas dentro da AIVAX, e o loop retorna ao passo 2.
4. **Finalizar.** A AIVAX valida a [saída estruturada](https://docs.aivax.net/pt-br/docs/inference/chat-completions/structured-output.md) quando solicitado e retorna a resposta final ou as [chamadas de ferramenta do cliente](https://docs.aivax.net/pt-br/docs/inference/chat-completions/tools.md) que seu aplicativo deve executar.

Apenas o resultado final é retornado como uma mensagem do assistente. Com [streaming](https://docs.aivax.net/pt-br/docs/inference/chat-completions/streaming.md), você também recebe raciocínio, eventos de ferramenta e texto parcial conforme eles ocorrem.

## Endpoint

<div class="request-item post">
    <span>POST</span>
    <span>
        /v1/chat/completions
    </span>
</div>

O endpoint também possui o alias de API `/api/v1/chat/completions`.

Referência:

[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions))

## Inferência de longa duração

Como uma solicitação pode executar várias gerações e ferramentas, ela pode levar minutos. Em `https://inference.aivax.net`, uma solicitação sem streaming que excede o tempo limite do proxy termina com HTTP `524`, enquanto a AIVAX continua processando-a. Envie solicitações longas para o host de inferência direto em vez disso:

```text
https://direct.inference.aivax.net/v1
```

A solicitação ainda é síncrona: mantenha a conexão aberta e defina um tempo limite do cliente que cubra o tempo de processamento esperado. Caminhos, chaves e corpos de solicitação são os mesmos do host padrão. Solicitações de streaming enviam dados continuamente e raramente precisam disso. Consulte [Inferência de longa duração](https://docs.aivax.net/pt-br/docs/overview.md#long-running-inference) para um exemplo de SDK e os endpoints que o host direto atende.

## Metadados da solicitação

Defina `metadata` para anexar informações de chave/valor string à solicitação de inferência. A AIVAX armazena este objeto junto com a conversa registrada e o expõe aos eventos do gateway, sendo útil para correlação operacional, como ID de pedido, inquilino, fluxo de trabalho ou chave de rastreamento interna.

```json
{
    "model": "your-model-or-gateway-id",
    "messages": [
        {
            "role": "user",
            "content": "Summarize this support ticket."
        }
    ],
    "metadata": {
        "ticket_id": "SUP-1042",
        "workflow": "support-triage"
    }
}
```

`metadata` deve ser um objeto JSON cujos nomes de propriedade e valores sejam strings. Não coloque segredos, credenciais, dados de pagamento ou cargas úteis grandes neste campo.

## Respostas e registros de conversa

O envelope de resposta padrão `/v1/chat/completions` inclui `generation_context`. Suas entradas `generated_usage` contêm `sku`, `amount`, `unit_price`, `quantity` e `description`. Defina [`json_only: true`](https://docs.aivax.net/pt-br/docs/inference/structured-responses/json-only.md) para retornar apenas o JSON final sem este envelope.

`usage` relata `prompt_tokens`, `completion_tokens` e `total_tokens`. `prompt_tokens` conta apenas a entrada não em cache; a entrada em cache é relatada separadamente em `prompt_tokens_details.cached_tokens`. Consulte [Cache](https://docs.aivax.net/pt-br/docs/inference/chat-completions/caching.md).

As respostas para modelos integrados também incluem `provider`, a tag do provedor que atendeu à solicitação; consulte [Provedor nas respostas](https://docs.aivax.net/pt-br/docs/inference/routing/setup-routing.md#provider-in-responses).

Defina `allow_logging: false` em uma solicitação `/v1/chat/completions` para manter essa solicitação fora dos logs de conversa da conta. Ela é definida como `true` por padrão e não pode habilitar o registro de log quando o registro de conversas está desabilitado para a conta. Os registros de uso e faturamento ainda são criados.

Quando o registro de conversas está habilitado, o registro armazenado inclui seu ID, origem, nome do modelo, ID da solicitação, esquema de resposta, esquemas de ferramentas e entrada de ferramentas, uso, recursos vinculados, carimbos de data/hora de criação e atualização, contagem de tokens, ID de usuário externo, mensagem de erro, mensagens e metadados. O contexto do gateway e da chave de API está disponível por meio dos recursos vinculados.

Use `conversation_token` e `metadata` para correlacionar esses registros com seu próprio fluxo de trabalho.

## Preços

As taxas de inferência dependem do modelo selecionado, do provedor, do tamanho da entrada e do tipo de mídia. A moderação é cobrada separadamente em Unidades de Processamento (PUs), cobrindo o uso de entrada, entrada em cache e saída; seu preço de PU varia com o modelo e o provedor utilizados. O [multiplicador de plano](https://docs.aivax.net/pt-br/docs/pricing.md#plan-multipliers) aplica-se à inferência de modelos integrados e à moderação. O BYOK (Bring Your Own Key) não é afetado por ele.

| Descrição | Preço |
| --- | ---: |
| Inferência de modelo de IA e Gateway de IA | Taxas do modelo e provedor selecionados |
| Moderação de entrada | Preço variável por PU; separado da cobrança principal de inferência |

Uma PU de moderação equivale a um token de saída do modelo de moderação, e os tokens de entrada contam proporcionalmente ao seu preço. Por exemplo, com um modelo precificado em $0,10/M de tokens de entrada e $0,40/M de tokens de saída, uma verificação usando 3.000 tokens de entrada e 50 tokens de saída consome 800 PUs (3.000 × 0,25 + 50), cerca de $0,00032 antes do multiplicador de plano.