Utilisation des SDK et de l'API

FlexInference accepte les requêtes compatibles OpenAI. Conservez le SDK OpenAI officiel ou curl, définissez l’URL de base sur FlexInference, authentifiez-vous avec votre clé flex_live_, et envoyez le champ start_within requis à chaque requête. Si vous l’omettez, vous recevrez 400 missing_start_within.

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

FlexInference prend en charge quatre points de terminaison POST et traduit chaque format d’appelant vers la surface du fournisseur sélectionnée par le planificateur :

POST /v1/responses : l’API Responses
POST /v1/chat/completions : l’API Chat Completions
POST /v1/interactions : l’API Interactions (fonctionne avec les modèles OpenAI, Gemini et Anthropic)
POST /v1/messages : l’API Anthropic Messages (fonctionne avec n’importe quel modèle)

Chaque point de terminaison accepte également le tableau provider ordonné et facultatif pour épingler la route ; voir Épingler la route ci-dessous. Le SDK OpenAI couvre /v1/responses et /v1/chat/completions. Il n’expose pas /v1/interactions ou /v1/messages, vous pouvez donc y accéder avec curl ou les SDK natifs FlexInference (Python, TypeScript).

Configurer le client

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"

Transmettre `start_within`

start_within indique à FlexInference combien de temps il peut attendre avant que la requête ne commence à renvoyer des résultats. Utilisez une durée telle que 00h-01m-00s pour une minute. Une durée lance la “flex race” : le planificateur essaie un niveau flex moins cher dans ce budget, puis passe au niveau standard si flex ne peut pas démarrer à temps. Les SDK OpenAI ne typent pas start_within, vous devez donc le transmettre via extra_body en Python et un objet de requête non typé 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"
  }'

Voir Deadline routing pour l’ensemble complet des valeurs.

Lire le résultat flex

Lisez service_tier dans le corps de la réponse ainsi que les en-têtes de réponse x-flexinference-flex-*. x-flexinference-flex-applied indique si flex a servi la réponse. x-flexinference-flex-reason fournit le résultat lisible par machine, y compris flex_committed et flex_lost_race. Une durée qui ne peut pas exécuter une “flex race” renvoie 400 flex_unsupported_for_anthropic ou 400 flex_model_not_capable. Consultez Deadline routing pour savoir comment lire les en-têtes et Errors pour la liste complète.

Streaming

Définissez stream: true et consommez les événements comme vous le feriez avec OpenAI. Le streaming ne modifie pas le routage. FlexInference s’engage d’abord sur un niveau, puis diffuse les tokens après que ce niveau commence à répondre.

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

Délais d’attente (Timeouts)

start_within définit la limite de temps pour le début de la requête, et non le temps total de génération. FlexInference maintient la réponse HTTP jusqu’à ce qu’un niveau s’engage. Une fois que flex s’est engagé, il s’exécute jusqu’à la fin ; FlexInference ne bascule pas une requête engagée vers le standard parce que la génération est lente. Définissez le délai d’attente de votre client pour couvrir la fenêtre d’attente plus le temps dont le modèle a besoin pour répondre. Le SDK OpenAI utilise par défaut un délai d’attente de 10 minutes, ce qui correspond au start_within le plus long autorisé. Si la génération peut commencer vers la fin d’une longue fenêtre, augmentez le délai d’attente au-delà de la valeur par défaut. Un délai d’attente plus court peut annuler la requête avant que FlexInference ne renvoie un résultat. Voir 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
});

Les SDK natifs FlexInference (Python, TypeScript) gèrent cela automatiquement. Ils dimensionnent l’attente de la première réponse à partir de start_within, limitent les flux bloqués avec un délai d’inactivité, et laissent les flux sans limite totale afin que les réponses longues puissent se terminer. Les appels non-streaming conservent un budget total. Chaque délai d’attente est configurable sur le client et par requête.

Réessayer les échecs transitoires en amont

Ajoutez un objet retry facultatif pour relancer le niveau qui traite votre requête lorsqu’il ne parvient pas à démarrer avec une erreur transitoire 429 ou 5xx. Transmettez-le de la même manière que vous transmettez 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 à 5, backoff est "exponential" (par défaut) ou "linear", et jitter est true par défaut. La nouvelle tentative ne se produit qu’avant que la réponse ne soit validée, respecte l’en-tête Retry-After du fournisseur et s’ajoute aux propres tentatives de votre SDK client. Voir Deadline routing pour le comportement complet et l’en-tête de réponse x-flexinference-retries.

Épingler la route

Un tableau provider ordonné et facultatif épingle la route du fournisseur qui traite votre requête. Il s’applique à chaque point de terminaison : /v1/responses, /v1/chat/completions, /v1/interactions et /v1/messages. L’élément 0 est la route principale et la seule porte flex ; les éléments 1 à n sont la chaîne de secours du même modèle, essayée dans l’ordre lorsqu’une route échoue de manière transitoire. Si vous l’omettez, FlexInference utilise la route native du modèle. Transmettez-le de la même manière que vous transmettez start_within. Chaque route que vous nommez doit d’abord avoir sa clé configurée. Une clé manquante renvoie une erreur 400 pour cette route et ne passe jamais à la suivante, alors ajoutez la clé de chaque route dans le tableau de bord avant de la nommer. Voir 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 et anthropic sont des routes directes. vertex (Gemini) et bedrock (Claude) sont des routes cloud qui servent le même modèle sur Google Vertex AI et Amazon Bedrock ; chacune nécessite sa propre clé BYOK du cloud. Un tableau invalide renvoie 400 invalid_provider_chain, une route qui ne peut pas servir le modèle renvoie 400 provider_model_mismatch, et une durée start_within avec une route cloud en premier renvoie 400 flex_unsupported_on_cloud. Les SDK natifs FlexInference typent provider et vérifient sa forme localement avant que la requête ne quitte votre processus ; le SDK OpenAI ne le type pas, vous devez donc le transmettre via extra_body ou un objet non typé. Voir provider routing pour la matrice des chaînes valides.

Chat Completions

Chat Completions utilise les mêmes règles start_within. Une durée lance la “flex race” lorsque la requête peut être acheminée via les Réponses canoniques. Les requêtes OpenAI Chat sont acheminées via les Réponses canoniques, sauf si un paramètre Chat natif nécessite un passthrough OpenAI Chat ; les paramètres Chat uniquement natifs ne peuvent pas être combinés avec une durée 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

Le point de terminaison Interactions est un autre format d’appelant pour les modèles OpenAI, Gemini et Anthropic. start_within s’applique de la même manière. Envoyez input sous forme de chaîne de caractères, de tableau de contenu de parties, ou de liste d’étapes multi-tours. system_instruction, tools et response_format correspondent aux mêmes fonctionnalités en amont.

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 réponse est un objet interaction. La sortie se trouve dans steps. usage répartit le nombre de tokens entre l’entrée, la sortie, la réflexion, le cache, l’utilisation d’outils et le 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 est requires_action lorsqu’une étape est un function_call, incomplete lorsque la sortie est tronquée, failed en cas d’erreur, et completed autrement. generation_config.thinking_level correspond à reasoning.effort. Les clés generation_config.* supplémentaires sont transmises sur les modèles Gemini. Sur les modèles non-Gemini, toute clé generation_config.* non mappée échoue avec unsupported_generation_config. Un service_tier fourni par l’appelant est refusé avec service_tier_not_allowed ; voir Errors. FlexInference dérive la sélection du niveau de start_within. Si vous envoyez service_tier, la requête échoue avec service_tier_not_allowed. Supprimez le champ et exprimez le niveau via start_within. Voir Errors pour la liste complète et les exemples de corps.

Messages

Le point de terminaison Messages utilise la forme de requête et de réponse Anthropic Messages. Il fonctionne avec n’importe quel modèle car FlexInference traduit via la forme canonique. start_within est requis. Anthropic exige max_tokens ; FlexInference le transmet lorsque vous le définissez et ne synthétise pas de valeur par défaut si vous l’omettez. Envoyez messages sous forme de tours {role, content}, avec content comme chaîne de caractères ou tableau de blocs de contenu. system, tools, tool_choice et thinking correspondent aux mêmes fonctionnalités en amont.

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 réponse est un objet message Anthropic. La sortie se trouve dans content sous forme de blocs text, thinking et tool_use. usage.service_tier est le niveau de service utilisé, soit flex, soit 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 est end_turn pour une fin normale, max_tokens lorsque tronqué, tool_use lorsque le modèle appelle un outil, et refusal lorsqu’il refuse. thinking correspond à reasoning.effort par modèle. Sur les modèles Claude, les champs natifs Anthropic tels que top_k, stop_sequences, les blocs cache_control, les citations et les blocs de contenu document ou file sont transmis. Sur les modèles OpenAI ou Gemini, les blocs de contenu document et file avec des sources base64 sont traduits en input_file canonique et ne sont pas rejetés. Les documents URL distants dépendent toujours du support propre au fournisseur cible. D’autres champs natifs Anthropic, y compris top_k, stop_sequences, les blocs cache_control et les citations, échouent avec unsupported_parameter entre fournisseurs. Un service_tier fourni par l’appelant échoue toujours avec service_tier_not_allowed ; voir Errors.

Tout le reste fonctionne sans changement

L’appel d’outils (tool calling), les sorties structurées (response_format), la vision et le raisonnement sont transmis au fournisseur sélectionné. Utilisez les champs normaux du fournisseur pour ces fonctionnalités.

Les paramètres natifs de Chat sont transmis sur les modèles OpenAI lorsque le passthrough natif de Chat est requis : presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, seed, stop, prediction, audio, les modalities non-textuelles et web_search_options. Sur les modèles Gemini ou Claude, la définition de l’un de ces champs à une valeur réelle échoue avec unsupported_parameter. n > 1 pour Chat Completions échoue toujours avec unsupported_value. Pour la recherche web sur le chemin canonique, utilisez un outil web_search de l’API Responses.

Prise en main

Concepts

Utiliser l'API

Foire aux questions

Utilisation des SDK et de l'API

Configurer le client

Transmettre `start_within`

Lire le résultat flex

Streaming

Délais d’attente (Timeouts)

Réessayer les échecs transitoires en amont

Épingler la route

Chat Completions

Interactions

Messages

Tout le reste fonctionne sans changement

​Configurer le client

​Transmettre start_within

​Lire le résultat flex

​Streaming

​Délais d’attente (Timeouts)

​Réessayer les échecs transitoires en amont

​Épingler la route

​Chat Completions

​Interactions

​Messages

​Tout le reste fonctionne sans changement

Configurer le client

Transmettre `start_within`

Lire le résultat flex

Streaming

Délais d’attente (Timeouts)

Réessayer les échecs transitoires en amont

Épingler la route

Chat Completions

Interactions

Messages

Tout le reste fonctionne sans changement