SDKs y uso de la API

FlexInference acepta solicitudes compatibles con OpenAI. Mantenga el SDK oficial de OpenAI o curl, establezca la URL base a FlexInference, autentíquese con su clave flex_live_ y envíe el campo start_within requerido en cada solicitud. Omítalo y obtendrá 400 missing_start_within.

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

FlexInference admite cuatro endpoints POST y traduce la forma de cada llamada a la superficie del proveedor seleccionada por el planificador:

POST /v1/responses: la API de Responses
POST /v1/chat/completions: la API de Chat Completions
POST /v1/interactions: la API de Interactions (funciona con modelos OpenAI, Gemini y Anthropic)
POST /v1/messages: la API de Anthropic Messages (funciona con cualquier modelo)

Cada endpoint también acepta el array provider opcional y ordenado para fijar la ruta; consulte Fijar la ruta a continuación. El SDK de OpenAI cubre /v1/responses y /v1/chat/completions. No expone /v1/interactions ni /v1/messages, por lo que puede acceder a ellos con curl o los SDK nativos de FlexInference (Python, TypeScript).

Configurar el 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"

Pasar `start_within`

start_within le indica a FlexInference cuánto tiempo puede esperar para que la solicitud comience a devolver resultados. Utilice una duración como 00h-01m-00s para un minuto. Una duración ejecuta la “carrera flex”: el planificador intenta una capa flex más económica dentro de ese presupuesto, luego escala a estándar cuando flex no puede comenzar a tiempo. Los SDK de OpenAI no tipifican start_within, así que páselo con extra_body en Python y un objeto de solicitud sin tipo en 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"
  }'

Consulte Enrutamiento por plazo para ver el conjunto completo de valores.

Leer el resultado flex

Lea service_tier en el cuerpo de la respuesta, además de los encabezados de respuesta x-flexinference-flex-*. x-flexinference-flex-applied indica si flex sirvió la respuesta. x-flexinference-flex-reason proporciona el resultado legible por máquina, incluyendo flex_committed y flex_lost_race. Una duración que no puede ejecutar una carrera flex devuelve 400 flex_unsupported_for_anthropic o 400 flex_model_not_capable. Consulte Enrutamiento por plazo para saber cómo leer los encabezados y Errores para ver la lista completa.

Streaming

Establezca stream: true y consuma eventos como lo haría con OpenAI. El streaming no cambia el enrutamiento. FlexInference se compromete primero con una capa, luego transmite tokens después de que esa capa comienza 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"
  }'

Tiempos de espera

start_within limita cuándo comienza la solicitud, no el tiempo total de generación. FlexInference mantiene la respuesta HTTP hasta que una capa se compromete. Después de que flex se compromete, se ejecuta hasta su finalización; FlexInference no cambia una solicitud comprometida a estándar porque la generación sea lenta. Establezca el tiempo de espera de su cliente para cubrir la ventana de espera más el tiempo que el modelo necesita para responder. El SDK de OpenAI tiene un tiempo de espera predeterminado de 10 minutos, lo que coincide con el start_within más largo permitido. Si la generación puede comenzar cerca del final de una ventana larga, aumente el tiempo de espera por encima del valor predeterminado. Un tiempo de espera más corto puede cancelar la solicitud antes de que FlexInference devuelva un resultado. Consulte 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
});

Los SDK nativos de FlexInference (Python, TypeScript) manejan esto automáticamente. Dimensionan la espera de la primera respuesta a partir de start_within, limitan los streams estancados con un tiempo de espera de inactividad y dejan los streams sin un límite total para que las respuestas largas puedan finalizar. Las llamadas sin streaming mantienen un presupuesto total. Cada tiempo de espera es configurable en el cliente y por solicitud.

Reintentar fallos transitorios del proveedor

Añada un objeto retry opcional para volver a intentar la capa que atiende su solicitud cuando esta no se inicia debido a un 429 o 5xx transitorio. Páselo de la misma manera que pasa 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 va de 1 a 5, backoff es "exponential" (predeterminado) o "linear", y jitter por defecto es true. El reintento solo se produce antes de que la respuesta se comprometa, respeta el Retry-After del proveedor y se acumula con los propios reintentos del SDK de su cliente. Consulte Enrutamiento por plazo para ver el comportamiento completo y el encabezado de respuesta x-flexinference-retries.

Fijar la ruta

Un array provider opcional y ordenado fija qué ruta de proveedor atiende su solicitud. Se aplica a cada endpoint: /v1/responses, /v1/chat/completions, /v1/interactions y /v1/messages. El elemento 0 es la ruta principal y la única puerta flex; los elementos 1 a n son la cadena de respaldo del mismo modelo, que se intenta en orden cuando una ruta falla transitoriamente. Omítalo y FlexInference utilizará la ruta nativa del modelo. Páselo de la misma manera que pasa start_within. Cada ruta que nombre necesita su clave configurada primero. Una clave faltante devuelve un 400 para esa ruta y nunca pasa a la siguiente, así que añada la clave de cada ruta en el panel antes de nombrarla. Consulte enrutamiento de proveedor.

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 y anthropic son rutas directas. vertex (Gemini) y bedrock (Claude) son rutas en la nube que sirven el mismo modelo en Google Vertex AI y Amazon Bedrock; cada una necesita su propia clave BYOK de esa nube. Un array inválido devuelve 400 invalid_provider_chain, una ruta que no puede servir el modelo devuelve 400 provider_model_mismatch, y una duración start_within con una ruta en la nube primero devuelve 400 flex_unsupported_on_cloud. Los SDK nativos de FlexInference tipifican provider y verifican su forma localmente antes de que la solicitud salga de su proceso; el SDK de OpenAI no lo tipifica, así que páselo a través de extra_body o un objeto sin tipo. Consulte enrutamiento de proveedor para ver la matriz de cadenas válidas.

Chat Completions

Chat Completions utiliza las mismas reglas de start_within. Una duración ejecuta la carrera flex cuando la solicitud puede enrutarse a través de Responses canónicas. Las solicitudes de Chat de OpenAI se enrutan a través de Responses canónicas a menos que un parámetro de Chat nativo requiera el paso directo de Chat de OpenAI; los parámetros de Chat solo nativos no se pueden combinar con una duración 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

El endpoint Interactions es otro formato de llamada para modelos OpenAI, Gemini y Anthropic. start_within se aplica de la misma manera. Envíe input como una cadena, un array de contenido de partes o una lista de pasos de múltiples turnos. system_instruction, tools y response_format se mapean a las mismas características del proveedor.

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

La respuesta es un objeto interaction. La salida está en steps. usage divide los recuentos de tokens entre input, output, thought, cached, tool-use y 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 es requires_action cuando un paso es una function_call, incomplete cuando la salida está truncada, failed en caso de error y completed en caso contrario. generation_config.thinking_level se mapea a reasoning.effort. Las claves generation_config.* adicionales se pasan directamente en los modelos Gemini. En los modelos no Gemini, cualquier clave generation_config.* no mapeada falla con unsupported_generation_config. Un service_tier proporcionado por el llamador es rechazado con service_tier_not_allowed; consulte Errores. FlexInference deriva la selección de la capa de start_within. Si envía service_tier, la solicitud falla con service_tier_not_allowed. Elimine el campo y exprese la capa a través de start_within. Consulte Errores para ver la lista completa y los cuerpos de ejemplo.

Messages

El endpoint Messages utiliza la forma de solicitud y respuesta de Anthropic Messages. Funciona con cualquier modelo porque FlexInference traduce a través del formato canónico. start_within es obligatorio. Anthropic requiere max_tokens; FlexInference lo reenvía cuando usted lo establece y no sintetiza un valor predeterminado si lo omite. Envíe messages como turnos {role, content}, con content como una cadena o un array de bloques de contenido. system, tools, tool_choice y thinking se mapean a las mismas características del proveedor.

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

La respuesta es un objeto message de Anthropic. La salida está en content como bloques de text, thinking y tool_use. usage.service_tier es la capa servida, ya sea flex o estándar.

{
  "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 es end_turn en una finalización normal, max_tokens cuando se trunca, tool_use cuando el modelo llama a una herramienta y refusal cuando se niega. thinking se mapea a reasoning.effort por modelo. En los modelos Claude, los campos nativos de Anthropic como top_k, stop_sequences, bloques cache_control, citas y bloques de contenido document o file se pasan directamente. En los modelos OpenAI o Gemini, los bloques de contenido document y file con fuentes base64 se traducen a input_file canónico y no se rechazan. Los documentos con URL remotas aún dependen del soporte del proveedor de destino. Otros campos nativos de Anthropic, incluidos top_k, stop_sequences, bloques cache_control y citas, fallan con unsupported_parameter entre proveedores. Un service_tier proporcionado por el llamador siempre falla con service_tier_not_allowed; consulte Errores.

Todo lo demás funciona sin cambios

La llamada a herramientas, las salidas estructuradas (response_format), la visión y el razonamiento se pasan al proveedor seleccionado. Utilice los campos normales del proveedor para esas características.

Los parámetros nativos de Chat se pasan directamente en los modelos OpenAI cuando se requiere el paso directo de Chat nativo: presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, seed, stop, prediction, audio, modalities no textuales y web_search_options. En los modelos Gemini o Claude, establecer cualquiera de esos campos con un valor real falla con unsupported_parameter. Chat Completions n > 1 siempre falla con unsupported_value. Para la búsqueda web en la ruta canónica, utilice una herramienta web_search de Responses.

Primeros pasos

Conceptos

Uso de la API

Preguntas frecuentes

Configurar el cliente

Pasar `start_within`

Leer el resultado flex

Streaming

Tiempos de espera

Reintentar fallos transitorios del proveedor

Fijar la ruta

Chat Completions

Interactions

Messages

Todo lo demás funciona sin cambios

​Configurar el cliente

​Pasar start_within

​Leer el resultado flex

​Streaming

​Tiempos de espera

​Reintentar fallos transitorios del proveedor

​Fijar la ruta

​Chat Completions

​Interactions

​Messages

​Todo lo demás funciona sin cambios

Configurar el cliente

Pasar `start_within`

Leer el resultado flex

Streaming

Tiempos de espera

Reintentar fallos transitorios del proveedor

Fijar la ruta

Chat Completions

Interactions

Messages

Todo lo demás funciona sin cambios