SDKs e uso da API

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 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, TypeScript).

Configurar o cliente

from openai import OpenAI

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

import OpenAI from "openai";

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

export FLEX_API_KEY="flex_live_..."
export FLEX_BASE_URL="https://api.flexinference.com/v1"

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.

resp = client.responses.create(
    model="gpt-5.5",
    input="Summarize this contract.",
    extra_body={"start_within": "00h-01m-00s"},
)

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

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"
  }'

Veja 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 para saber como ler os cabeçalhos e 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.

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="")

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);
}

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"
  }'

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.

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
)

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
});

Os SDKs nativos do FlexInference (Python, TypeScript) 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.

resp = client.responses.create(
    model="gpt-5.5",
    input="Summarize this contract.",
    extra_body={"start_within": "00h-01m-00s", "retry": {"count": 2}},
)

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

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 }
  }'

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

resp = client.responses.create(
    model="gpt-5.5",
    input="Summarize this contract.",
    extra_body={"start_within": "default", "provider": ["openai"]},
)

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

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"]
  }'

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

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)

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);

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.

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))

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));

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"
  }'

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.

{
  "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. 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 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.

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))

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));

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"
  }'

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.

{
  "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.

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.

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.

Primeiros passos

Conceitos

Usando a API

Perguntas frequentes

Configurar o cliente

Passando `start_within`

Lendo o resultado do flex

Streaming

Timeouts

Retentando falhas transitórias upstream

Fixando a rota

Chat Completions

Interactions

Messages

Tudo o mais funciona inalterado

​Configurar o cliente

​Passando start_within

​Lendo o resultado do flex

​Streaming

​Timeouts

​Retentando falhas transitórias upstream

​Fixando a rota

​Chat Completions

​Interactions

​Messages

​Tudo o mais funciona inalterado

Configurar o cliente

Passando `start_within`

Lendo o resultado do flex

Streaming

Timeouts

Retentando falhas transitórias upstream

Fixando a rota

Chat Completions

Interactions

Messages

Tudo o mais funciona inalterado