> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roteamento por prazo

> O campo start_within, a corrida flex e a escalada automática para o padrão.

`start_within` é obrigatório em cada requisição FlexInference. Ele define por quanto tempo o roteador pode esperar que a requisição seja iniciada. Use `default`, `priority` ou `auto` quando quiser um nível de provedor diretamente. Use uma duração quando quiser que o FlexInference tente o flex primeiro em um modelo capaz de flex, e então escale para o padrão se o flex não puder iniciar a tempo.

O campo possui quatro formas.

## As quatro formas

<Tabs>
  <Tab title="default">
    ```json theme={null}
    { "start_within": "default" }
    ```

    Encaminha para o nível **padrão** em tempo real do provedor com preço padrão: `default` da OpenAI, `standard` da Gemini ou `standard_only` da Anthropic. Funciona com qualquer modelo.
  </Tab>

  <Tab title="priority">
    ```json theme={null}
    { "start_within": "priority" }
    ```

    Encaminha para o nível **priority** da OpenAI para o início mais rápido. Use-o para caminhos interativos e críticos em termos de latência. Priority é o nível mais caro. Funciona com qualquer modelo. Na Anthropic, isso é **melhor esforço** porque Claude não tem um nível priority; nós o mapeamos para o `auto` da Anthropic.
  </Tab>

  <Tab title="auto">
    ```json theme={null}
    { "start_within": "auto" }
    ```

    Permite que o provedor escolha o nível. Na OpenAI, isso é `service_tier: auto`; na Anthropic, ele mapeia para o `auto` da Anthropic. Este é o nível `auto` do provedor, não o roteamento automático do FlexInference. Funciona na **OpenAI e Anthropic**. Gemini não tem um nível `auto`, então `auto` em um modelo Gemini retorna `400 auto_unsupported_for_gemini`.
  </Tab>

  <Tab title="uma duração">
    ```json theme={null}
    { "start_within": "00h-00m-30s" }
    ```

    Solicita a **corrida flex** (abaixo) em cada endpoint, incluindo `/v1/responses`, `/v1/chat/completions`, `/v1/interactions` e `/v1/messages`. O FlexInference tenta primeiro o nível flex mais barato e só muda para o padrão quando o flex não consegue iniciar dentro do prazo. A duração é o tempo máximo de espera para o início da requisição, escrito como `HHh-MMm-SSs` com dois dígitos por campo. Deve estar entre **5 segundos e 10 minutos** (`00h-00m-05s` a `00h-10m-00s`).
  </Tab>
</Tabs>

`default`, `priority` e `auto` fazem proxy de **qualquer** modelo para seu provedor (OpenAI, Gemini ou Anthropic). Apenas uma duração solicita a corrida flex. Se o modelo não puder usar flex, uma duração retorna `400` (`flex_unsupported_for_anthropic` ou `flex_model_not_capable`); use um valor de nível em vez disso.

<Note>
  A corrida flex **não está disponível no Claude** porque a Anthropic não possui
  um nível flex. Uma duração `start_within` em um modelo `claude-*` retorna
  `400 flex_unsupported_for_anthropic`. A Anthropic ainda funciona com
  requisições de proxy de nível `default`, `priority` e `auto`.
</Note>

<Note>
  Uma duração `start_within` não pode ser combinada com parâmetros de Chat
  Completions apenas nativos, como `logprobs` ou `seed`. Remova esses
  parâmetros ou use `default`, `priority` ou `auto` em vez disso.
</Note>

## A corrida flex

Com uma duração, o FlexInference tenta primeiro o nível **flex** do provedor (OpenAI ou Gemini). O flex é cobrado pela metade da taxa padrão, mas a capacidade é de melhor esforço. O roteador aguarda o início da requisição upstream dentro do seu prazo:

<Steps>
  <Step title="Disparar flex">
    O FlexInference envia sua requisição para o nível flex e aguarda a
    confirmação do provedor de que ela está sendo atendida, tudo dentro do
    tempo que você definiu.
  </Step>

  <Step title="Comprometer-se com flex">
    Se o provedor iniciar a requisição a tempo, o FlexInference se compromete.
    Sua resposta é transmitida normalmente, cobrada a taxas flex. A resposta
    mostra `"service_tier": "flex"`.
  </Step>

  <Step title="Escalar para o padrão">
    Se o flex não puder iniciar a tempo, o FlexInference o cancela e envia a
    requisição para o padrão. Esta é uma escalada do flex mais barato para o
    padrão, não um downgrade. A resposta mostra
    `"service_tier": "default"` (OpenAI) ou `"standard"` (Gemini).
  </Step>
</Steps>

A escalada para o padrão ocorre apenas antes do início do flex, quando o flex retorna um `429` (sem capacidade), qualquer `5xx`, uma falha pré-início ou nenhum início antes do prazo. A mudança de flex para padrão é a **única** alteração de nível que o FlexInference faz. Um fallback de provedor, onde você define um array `provider` opcional e o FlexInference tenta a próxima rota após uma rota falhar transitoriamente, muda a rota, nunca o nível ou o modelo. Uma chave ausente para qualquer rota que você nomeou é um erro de configuração em vez de uma falha transitória, então retorna um `400` em vez de prosseguir. Consulte [roteamento de provedor](/pt/models).

<Info>
  Escolha a duração mais longa que sua UX pode tolerar. Prazos mais longos dão
  ao flex mais tempo para vencer, aumentando a proporção de requisições
  atendidas com a taxa mais barata.
</Info>

## Lendo o resultado

Respostas `200` bem-sucedidas incluem cabeçalhos de resultado Flex em cada endpoint, tanto para chamadas de streaming quanto para não-streaming. Respostas de erro usam o corpo do erro em vez disso.

| Cabeçalho                          | Significado                                                                                                                                                                                                                                                                                                                                                                       |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-flexinference-flex-requested`   | `true` quando o chamador enviou uma duração `start_within`; `false` quando o chamador enviou `default`, `priority` ou `auto`.                                                                                                                                                                                                                                                     |
| `x-flexinference-flex-applied`     | `true` apenas quando o flex atendeu à resposta.                                                                                                                                                                                                                                                                                                                                   |
| `x-flexinference-flex-reason`      | O resultado legível por máquina. Veja os valores abaixo.                                                                                                                                                                                                                                                                                                                          |
| `x-flexinference-provider-surface` | A superfície do provedor selecionada pelo planejador. Os valores são `openai.responses`, `openai.chat`, `gemini.interactions` e `anthropic.messages`. Isso pode diferir do endpoint do chamador. Uma chamada `/v1/chat/completions` com um modelo OpenAI reporta `openai.responses`, a menos que o passthrough nativo de Chat seja necessário, caso em que reporta `openai.chat`. |

Os valores `x-flexinference-flex-reason` ao vivo são:

| Razão            | Significado                                                                                                                 |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `not_requested`  | A requisição usou `default`, `priority` ou `auto`; nenhuma corrida flex foi solicitada.                                     |
| `flex_committed` | A corrida flex foi comprometida. A resposta mostra `service_tier: "flex"` e `x-flexinference-flex-applied: true`.           |
| `flex_lost_race` | A requisição usou uma duração em um modelo capaz de flex, mas o flex não iniciou a tempo e a requisição retornou ao padrão. |

<Note>
  Uma duração que não pode executar uma corrida flex retorna `400`
  (`flex_unsupported_for_anthropic` em um modelo `claude-*`,
  `flex_model_not_capable` em um modelo OpenAI/Gemini não capaz de flex); as
  razões do cabeçalho descrevem apenas requisições que executaram flex ou não o
  solicitaram.
</Note>

## Quando o pool flex está indisponível

O nível flex usa capacidade compartilhada e de melhor esforço. Antes do início de uma requisição, o flex pode retornar um `429` quando não há capacidade, retornar qualquer `5xx`, falhar antes do início ou perder o prazo. O FlexInference então envia a requisição para o padrão.

Em casos raros, o flex falha *depois* que a requisição foi aceita e começou a transmitir. O FlexInference expõe essa falha. Em uma requisição de streaming, você recebe um evento `response.failed` terminal. Em uma requisição não-streaming, você recebe um `502`. Ele não tenta novamente após o comprometimento porque isso poderia mascarar uma requisição incompleta. Se isso acontecer, **tente novamente**, ou use `default`, `priority` ou `auto` para pular o flex.

## Retentativa de transporte

A corrida flex decide qual nível atende à sua requisição. A retentativa de transporte decide o que acontece quando esse nível falha ao iniciar. Adicione um objeto `retry` opcional e o FlexInference aguarda e tenta novamente o nível estabelecido em caso de falha upstream transitória, em vez de retornar o erro para você.

```json theme={null}
{ "retry": { "count": 2 } }
```

| Campo     | Obrigatório | Valores                                | Significado                                                                                                                 |
| :-------- | :---------- | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `count`   | sim         | inteiro, `1` a `5`                     | Novas tentativas no nível estabelecido após a primeira tentativa falhar.                                                    |
| `backoff` | não         | `"exponential"` (padrão) ou `"linear"` | O padrão de espera entre as tentativas. Exponencial começa em 0.5s e dobra até 8s; linear adiciona 0.5s a cada vez, até 8s. |
| `jitter`  | não         | booleano (padrão `true`)               | Distribui a espera para suavizar picos. O jitter apenas encurta uma espera, nunca a alonga.                                 |

Um `retry` inválido retorna `400` [`invalid_retry`](/pt/errors#invalid_retry).

O FlexInference tenta novamente apenas uma falha de transporte genuína pré-comprometimento do nível estabelecido: um `429` real, um `5xx` real ou uma conexão que nunca foi aberta ([`upstream_unavailable`](/pt/errors#upstream_unavailable)). Ele não tenta novamente um `4xx` do cliente, uma falha de autenticação upstream ([`upstream_auth_failed`](/pt/errors#upstream_auth_failed)), um timeout upstream ([`upstream_timeout`](/pt/errors#upstream_timeout)) ou uma requisição que o cliente cancelou. Esses falham da mesma forma em uma nova tentativa ou significam que o chamador já se foi.

A retentativa tenta novamente o nível que estabeleceu sua requisição, não a perna flex. Em uma requisição `default`, `priority` ou `auto`, esse é o nível que você nomeou. Em uma requisição de duração que perde a corrida flex, é o nível padrão para o qual você escalou. A tentativa flex e a escalada são o trabalho próprio da corrida flex e nunca contam contra `count`. Escalar um nível e tentar novamente o mesmo nível são etapas separadas que se encadeiam: o flex perde para o padrão, então o padrão pode tentar novamente.

Quando o provedor envia um cabeçalho `Retry-After`, o FlexInference espera esse tempo em vez do cronograma de backoff, limitado a 60 segundos para que um valor ruim não possa estacionar sua requisição.

<Note>
  A retentativa é apenas pré-comprometimento. Ela para no momento em que um
  nível se compromete, que é a linha de status `200` para chamadas de streaming
  e não-streaming. Uma vez que o primeiro byte está a caminho de você, o
  FlexInference nunca tenta novamente, a mesma regra que a corrida flex segue
  após o comprometimento. Uma falha no meio do stream, ou um `502`
  não-streaming após um `200` comprometido, é repassada para você.
</Note>

A `retry` do lado do servidor é separada de qualquer loop de retentativa em seu cliente, e os dois se acumulam. Os SDKs do FlexInference não tentam novamente, mas um SDK padrão da OpenAI ou Anthropic tenta novamente duas vezes por padrão. Um cliente que tenta novamente duas vezes além de um `count` de `3` no servidor gera até seis tentativas upstream, porque cada tentativa do cliente executa um orçamento completo do servidor. Quando você define `retry`, o FlexInference carimba `x-flexinference-retries` na resposta com o número de novas tentativas que executou, para que você possa diminuir o `max_retries` do seu cliente.

## Cobrança

Com BYOK, o FlexInference usa sua chave de provedor criptografada armazenada no lado do servidor; você não envia chaves de provedor por requisição. Seu provedor cobra sua conta pela taxa do nível que atendeu à requisição. Você paga taxas flex quando o flex se compromete e taxas padrão após a escalada. Uma tentativa flex pode consumir alguns tokens antes de falhar. Seu provedor cobra esse uso da mesma forma que cobraria se você chamasse o flex diretamente, e o FlexInference o inclui no uso. O FlexInference não adiciona nenhuma margem de lucro aos seus tokens. Ele cobra 20% do dinheiro que economiza para você e não cobra nada quando não há economia.

## O que o FlexInference muda

O FlexInference pode mudar o nível. Ele não muda o significado da sua requisição ou o resultado do provedor. Ele nunca reescreve o status ou a mensagem de um provedor. Ele normaliza apenas o envelope de erro: um erro é retornado no formato do endpoint que você chamou (OpenAI em respostas e chat, Anthropic em mensagens, Google em interações), carregando o status e a mensagem do provedor, para que seu SDK possa analisá-lo. Consulte [Erros](/pt/errors).

<Note>
  `start_within` é **obrigatório**. Sem ele, a requisição retorna `400
      missing_start_within`, inclusive com um SDK OpenAI simples apontado para
  nossa URL base. Se você enviar um valor que o FlexInference não pode ler,
  você receberá `invalid_start_within`. Valores válidos são `"default"`,
  `"priority"`, `"auto"` ou uma duração como `"00h-00m-30s"`. A palavra
  `standard` costumava ser permitida e não é mais, então envie `default` em vez
  disso. Consulte [Erros](/pt/errors) para a lista completa.
</Note>