> ## 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.

# SDKs e uso da API

> Use o SDK OpenAI que você já possui. Altere a URL base, adicione start_within.

FlexInference aceita requisições compatíveis com OpenAI. Mantenha o SDK oficial do OpenAI ou `curl`, defina a URL base para FlexInference, autentique com sua chave `flex_live_` e envie o campo `start_within` obrigatório em cada requisição. Omita-o e você receberá `400 missing_start_within`.

```
Base URL   https://api.flexinference.com/v1
Auth       Authorization: Bearer flex_live_...
```

FlexInference suporta quatro endpoints POST e traduz cada formato de chamada para a superfície do provedor selecionada pelo planejador:

* `POST /v1/responses`: a API Responses
* `POST /v1/chat/completions`: a API Chat Completions
* `POST /v1/interactions`: a API Interactions (funciona com modelos OpenAI, Gemini e Anthropic)
* `POST /v1/messages`: a API Anthropic Messages (funciona com **qualquer** modelo)

Cada endpoint também aceita o array `provider` opcional e ordenado para fixar a rota; veja [Fixando a rota](#pinning-the-route) abaixo.

O SDK do OpenAI cobre `/v1/responses` e `/v1/chat/completions`. Ele não expõe `/v1/interactions` ou `/v1/messages`, então acesse-os com `curl` ou os SDKs nativos do FlexInference ([Python](https://pypi.org/project/flexinference/), [TypeScript](https://www.npmjs.com/package/flexinference)).

## Configurar o cliente

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.flexinference.com/v1",
      api_key="flex_live_...",
  )
  ```

  ```typescript Node theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.flexinference.com/v1",
    apiKey: "flex_live_...",
  });
  ```

  ```bash curl theme={null}
  export FLEX_API_KEY="flex_live_..."
  export FLEX_BASE_URL="https://api.flexinference.com/v1"
  ```
</CodeGroup>

## Passando `start_within`

`start_within` informa ao FlexInference quanto tempo ele pode esperar para que a requisição comece a retornar. Use uma duração como `00h-01m-00s` para um minuto. Uma duração executa a "flex race": o planejador tenta um tier flex mais barato dentro desse orçamento, então escala para o padrão quando o flex não consegue iniciar a tempo.

Os SDKs do OpenAI não tipam `start_within`, então passe-o com `extra_body` em Python e um objeto de requisição não tipado em Node.

<CodeGroup>
  ```python Python theme={null}
  resp = client.responses.create(
      model="gpt-5.5",
      input="Summarize this contract.",
      extra_body={"start_within": "00h-01m-00s"},
  )
  ```

  ```typescript Node theme={null}
  const resp = await client.responses.create({
    model: "gpt-5.5",
    input: "Summarize this contract.",
    start_within: "00h-01m-00s",
  } as any);
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/responses" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.5",
      "input": "Summarize this contract.",
      "start_within": "00h-01m-00s"
    }'
  ```
</CodeGroup>

Veja [Deadline routing](/pt/deadline-routing) para o conjunto completo de valores.

## Lendo o resultado do flex

Leia `service_tier` no corpo da resposta, além dos cabeçalhos de resposta `x-flexinference-flex-*`. `x-flexinference-flex-applied` indica se o flex atendeu à resposta. `x-flexinference-flex-reason` fornece o resultado legível por máquina, incluindo `flex_committed` e `flex_lost_race`. Uma duração que não pode executar uma "flex race" retorna `400 flex_unsupported_for_anthropic` ou `400 flex_model_not_capable`. Veja [Deadline routing](/pt/deadline-routing) para saber como ler os cabeçalhos e [Errors](/pt/errors) para a lista completa.

## Streaming

Defina `stream: true` e consuma eventos como faria com o OpenAI. O streaming não altera o roteamento. O FlexInference se compromete com um tier primeiro, então transmite os tokens depois que esse tier começa a responder.

<CodeGroup>
  ```python Python theme={null}
  stream = client.responses.create(
      model="gpt-5-nano",
      input="Count to ten.",
      stream=True,
      extra_body={"start_within": "00h-00m-20s"},
  )
  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="")
  ```

  ```typescript Node theme={null}
  const stream = await client.responses.create({
    model: "gpt-5-nano",
    input: "Count to ten.",
    stream: true,
    start_within: "00h-00m-20s",
  } as any);

  for await (const event of stream) {
    if (event.type === "response.output_text.delta")
      process.stdout.write(event.delta);
  }
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/responses" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5-nano",
      "input": "Count to ten.",
      "stream": true,
      "start_within": "00h-00m-20s"
    }'
  ```
</CodeGroup>

## Timeouts

`start_within` limita quando a requisição começa, não o tempo total de geração. O FlexInference mantém a resposta HTTP até que um tier se comprometa. Depois que o flex se compromete, ele é executado até a conclusão; o FlexInference não muda uma requisição comprometida para o padrão porque a geração é lenta. Defina o timeout do seu cliente para cobrir a janela de espera mais o tempo que o modelo precisa para responder.

O SDK do OpenAI tem um timeout padrão de 10 minutos, o que corresponde ao `start_within` mais longo permitido. Se a geração puder começar perto do final de uma janela longa, aumente o timeout acima do padrão. Um timeout mais curto pode cancelar a requisição antes que o FlexInference retorne um resultado. Veja [`client_closed_request`](/pt/errors#client_closed_request).

<CodeGroup>
  ```python Python theme={null}
  client = OpenAI(
      base_url="https://api.flexinference.com/v1",
      api_key="flex_live_...",
      timeout=600,  # seconds; keep it at least as long as your start_within
  )
  ```

  ```typescript Node theme={null}
  const client = new OpenAI({
    baseURL: "https://api.flexinference.com/v1",
    apiKey: "flex_live_...",
    timeout: 600_000, // ms; keep it at least as long as your start_within
  });
  ```
</CodeGroup>

Os SDKs nativos do FlexInference ([Python](https://pypi.org/project/flexinference/), [TypeScript](https://www.npmjs.com/package/flexinference)) lidam com isso automaticamente. Eles dimensionam a espera da primeira resposta a partir de `start_within`, limitam streams travados com um timeout de inatividade e deixam streams sem um limite total para que respostas longas possam ser concluídas. Chamadas não-streaming mantêm um orçamento total. Cada timeout é configurável no cliente e por requisição.

## Retentando falhas transitórias upstream

Adicione um objeto `retry` opcional para tentar novamente o tier que está atendendo à sua requisição quando ele falha ao iniciar com um `429` ou `5xx` transitório. Passe-o da mesma forma que você passa `start_within`.

<CodeGroup>
  ```python Python theme={null}
  resp = client.responses.create(
      model="gpt-5.5",
      input="Summarize this contract.",
      extra_body={"start_within": "00h-01m-00s", "retry": {"count": 2}},
  )
  ```

  ```typescript Node theme={null}
  const resp = await client.responses.create({
    model: "gpt-5.5",
    input: "Summarize this contract.",
    start_within: "00h-01m-00s",
    retry: { count: 2 },
  } as any);
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/responses" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.5",
      "input": "Summarize this contract.",
      "start_within": "00h-01m-00s",
      "retry": { "count": 2 }
    }'
  ```
</CodeGroup>

`count` varia de `1` a `5`, `backoff` é `"exponential"` (padrão) ou `"linear"`, e `jitter` é `true` por padrão. A retentativa ocorre apenas antes que a resposta se comprometa, respeita o `Retry-After` do provedor e se acumula com as próprias retentativas do SDK do seu cliente. Veja [Deadline routing](/pt/deadline-routing) para o comportamento completo e o cabeçalho de resposta `x-flexinference-retries`.

## Fixando a rota

Um array `provider` opcional e ordenado fixa qual rota de provedor atende à sua requisição. Ele se aplica a todos os endpoints: `/v1/responses`, `/v1/chat/completions`, `/v1/interactions` e `/v1/messages`. O elemento 0 é a rota primária e a única porta flex; os elementos 1 a n são a cadeia de fallback do mesmo modelo, tentada em ordem quando uma rota falha transitoriamente. Omita-o e o FlexInference usará a rota nativa do modelo. Passe-o da mesma forma que você passa `start_within`.

Cada rota que você nomeia precisa ter sua chave configurada primeiro. Uma chave ausente retorna um `400` para essa rota e nunca passa para a próxima, então adicione a chave de cada rota no painel antes de nomeá-la. Veja [provider routing](/pt/models).

<CodeGroup>
  ```python Python theme={null}
  resp = client.responses.create(
      model="gpt-5.5",
      input="Summarize this contract.",
      extra_body={"start_within": "default", "provider": ["openai"]},
  )
  ```

  ```typescript Node theme={null}
  const resp = await client.responses.create({
    model: "gpt-5.5",
    input: "Summarize this contract.",
    start_within: "default",
    provider: ["openai"],
  } as any);
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/responses" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.5",
      "input": "Summarize this contract.",
      "start_within": "default",
      "provider": ["openai"]
    }'
  ```
</CodeGroup>

`google`, `openai` e `anthropic` são rotas diretas. `vertex` (Gemini) e `bedrock` (Claude) são rotas de nuvem que servem o mesmo modelo no Google Vertex AI e Amazon Bedrock; cada uma precisa da própria chave BYOK dessa nuvem. Um array inválido retorna `400 invalid_provider_chain`, uma rota que não pode servir o modelo retorna `400 provider_model_mismatch`, e uma duração `start_within` com uma rota de nuvem primeiro retorna `400 flex_unsupported_on_cloud`. Os SDKs nativos do FlexInference tipam `provider` e verificam seu formato localmente antes que a requisição saia do seu processo; o SDK do OpenAI não o tipa, então passe-o através de `extra_body` ou um objeto não tipado. Veja [provider routing](/pt/models) para a matriz de cadeias válidas.

## Chat Completions

Chat Completions usa as mesmas regras de `start_within`. Uma duração executa a "flex race" quando a requisição pode ser roteada através de Responses canônicas. Requisições de Chat do OpenAI são roteadas através de Responses canônicas, a menos que um parâmetro de Chat nativo exija o passthrough de Chat do OpenAI; parâmetros de Chat apenas nativos não podem ser combinados com uma duração `start_within`.

<CodeGroup>
  ```python Python theme={null}
  resp = client.chat.completions.create(
      model="gpt-5.5",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"start_within": "default"},
  )
  print(resp.choices[0].message.content)
  ```

  ```typescript Node theme={null}
  const resp = await client.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "Hello!" }],
    start_within: "default",
  } as any);

  console.log(resp.choices[0].message.content);
  ```
</CodeGroup>

## Interactions

O endpoint Interactions é outro formato de chamada para modelos OpenAI, Gemini e Anthropic. `start_within` se aplica da mesma forma. Envie `input` como uma string, um array de conteúdo de partes ou uma lista de etapas multi-turn. `system_instruction`, `tools` e `response_format` mapeiam para os mesmos recursos upstream.

<CodeGroup>
  ```python Python theme={null}
  from flexinference import FlexInference, interaction_output_text

  client = FlexInference(api_key="flex_live_...")

  resp = client.interactions.create({
      "model": "gemini-3.5-flash",
      "input": "Summarize this contract.",
      "start_within": "00h-01m-00s",
  })
  print(interaction_output_text(resp))
  ```

  ```typescript Node theme={null}
  import { FlexInference, interactionText } from "flexinference";

  const client = new FlexInference({ apiKey: "flex_live_..." });

  const resp = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Summarize this contract.",
    start_within: "00h-01m-00s",
  });

  console.log(interactionText(resp));
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/interactions" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3.5-flash",
      "input": "Summarize this contract.",
      "start_within": "00h-01m-00s"
    }'
  ```
</CodeGroup>

A resposta é um objeto `interaction`. A saída está em `steps`. `usage` divide as contagens de tokens entre input, output, thought, cached, tool-use e total.

```json theme={null}
{
  "id": "interaction_...",
  "object": "interaction",
  "status": "completed",
  "model": "gemini-3.5-flash",
  "created": 1750000000,
  "updated": 1750000000,
  "service_tier": "flex",
  "usage": {
    "total_input_tokens": 1200,
    "total_output_tokens": 180,
    "total_thought_tokens": 64,
    "total_cached_tokens": 0,
    "total_tokens": 1444,
    "total_tool_use_tokens": 0
  },
  "steps": [
    { "type": "model_output", "content": [{ "type": "text", "text": "..." }] }
  ]
}
```

`status` é `requires_action` quando uma etapa é uma `function_call`, `incomplete` quando a saída é truncada, `failed` em caso de erro e `completed` caso contrário. `generation_config.thinking_level` mapeia para `reasoning.effort`. Chaves `generation_config.*` extras são passadas para modelos Gemini. Em modelos não-Gemini, qualquer chave `generation_config.*` não mapeada falha com `unsupported_generation_config`. Um `service_tier` fornecido pelo chamador é recusado com `service_tier_not_allowed`; veja [Errors](/pt/errors).

FlexInference deriva a seleção de tier de `start_within`. Se você enviar `service_tier`, a requisição falha com `service_tier_not_allowed`. Remova o campo e expresse o tier através de `start_within`. Veja [Errors](/pt/errors) para a lista completa e exemplos de corpos.

## Messages

O endpoint Messages usa o formato de requisição e resposta **Anthropic Messages**. Ele funciona com **qualquer** modelo porque o FlexInference traduz através do formato canônico. `start_within` é obrigatório. Anthropic requer `max_tokens`; o FlexInference o encaminha quando você o define e não sintetiza um padrão quando você o omite. Envie `messages` como turnos `{role, content}`, com `content` como uma string ou um array de blocos de conteúdo. `system`, `tools`, `tool_choice` e `thinking` mapeiam para os mesmos recursos upstream.

<CodeGroup>
  ```python Python theme={null}
  from flexinference import FlexInference, message_output_text

  client = FlexInference(api_key="flex_live_...")

  resp = client.messages.create({
      "model": "claude-opus-4-8",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Summarize this contract."}],
      "start_within": "default",
  })
  print(message_output_text(resp))
  ```

  ```typescript Node theme={null}
  import { FlexInference, messageText } from "flexinference";

  const client = new FlexInference({ apiKey: "flex_live_..." });

  const resp = await client.messages.create({
    model: "claude-opus-4-8",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Summarize this contract." }],
    start_within: "default",
  });

  console.log(messageText(resp));
  ```

  ```bash curl theme={null}
  curl "$FLEX_BASE_URL/messages" \
    -H "Authorization: Bearer $FLEX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-opus-4-8",
      "max_tokens": 1024,
      "messages": [{ "role": "user", "content": "Summarize this contract." }],
      "start_within": "default"
    }'
  ```
</CodeGroup>

A resposta é um objeto `message` do Anthropic. A saída está em `content` como blocos `text`, `thinking` e `tool_use`. `usage.service_tier` é o tier servido, seja flex ou standard.

```json theme={null}
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [{ "type": "text", "text": "..." }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1200,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 180,
    "output_tokens_details": { "thinking_tokens": 64 },
    "service_tier": "standard"
  }
}
```

`stop_reason` é `end_turn` em uma finalização normal, `max_tokens` quando truncado, `tool_use` quando o modelo chama uma ferramenta e `refusal` quando ele recusa. `thinking` mapeia para `reasoning.effort` por modelo. Em modelos Claude, campos nativos do Anthropic como `top_k`, `stop_sequences`, blocos `cache_control`, citações e blocos de conteúdo `document` ou `file` são passados. Em modelos OpenAI ou Gemini, blocos de conteúdo `document` e `file` com fontes base64 são traduzidos para `input_file` canônico e não são rejeitados. Documentos de URL remotos ainda dependem do suporte do provedor de destino. Outros campos nativos do Anthropic, incluindo `top_k`, `stop_sequences`, blocos `cache_control` e citações, falham com `unsupported_parameter` entre provedores. Um `service_tier` fornecido pelo chamador sempre falha com `service_tier_not_allowed`; veja [Errors](/pt/errors).

## Tudo o mais funciona inalterado

Chamada de ferramentas (tool calling), saídas estruturadas (`response_format`), visão e raciocínio são passados para o provedor selecionado. Use os campos normais do provedor para esses recursos.

<Warning>
  Parâmetros nativos de Chat são passados em modelos OpenAI quando o passthrough nativo de Chat é necessário: `presence_penalty`, `frequency_penalty`, `logit_bias`, `logprobs`, `top_logprobs`, `seed`, `stop`, `prediction`, `audio`, `modalities` não-texto e `web_search_options`. Em modelos Gemini ou Claude, definir qualquer um desses campos para um valor real falha com `unsupported_parameter`. `n > 1` em Chat Completions sempre falha com `unsupported_value`. Para pesquisa web no caminho canônico, use uma ferramenta `web_search` de Responses.
</Warning>