> ## 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 y uso de la API > Utilice el SDK de OpenAI que ya tiene. Cambie la URL base, añada start_within. 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](#pinning-the-route) 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](https://pypi.org/project/flexinference/), [TypeScript](https://www.npmjs.com/package/flexinference)). ## Configurar el cliente ```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" ``` ## 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. ```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" }' ``` Consulte [Enrutamiento por plazo](/es/deadline-routing) 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](/es/deadline-routing) para saber cómo leer los encabezados y [Errores](/es/errors) 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. ```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" }' ``` ## 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`](/es/errors#client_closed_request). ```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 }); ``` Los SDK nativos de FlexInference ([Python](https://pypi.org/project/flexinference/), [TypeScript](https://www.npmjs.com/package/flexinference)) 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`. ```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 } }' ``` `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](/es/deadline-routing) 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](/es/models). ```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"] }' ``` `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](/es/models) 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`. ```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); ``` ## 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. ```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" }' ``` 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`. ```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` 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](/es/errors). 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](/es/errors) 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. ```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" }' ``` 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. ```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` 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](/es/errors). ## 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.