SDKs und API-Nutzung

FlexInference akzeptiert OpenAI-kompatible Anfragen. Verwenden Sie das offizielle OpenAI SDK oder curl, setzen Sie die Basis-URL auf FlexInference, authentifizieren Sie sich mit Ihrem flex_live_-Schlüssel und senden Sie das erforderliche start_within-Feld bei jeder Anfrage mit. Wenn Sie es weglassen, erhalten Sie 400 missing_start_within.

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

FlexInference unterstützt vier POST-Endpunkte und übersetzt jede Aufruferform in die vom Planer ausgewählte provider-Oberfläche:

POST /v1/responses: die Responses API
POST /v1/chat/completions: die Chat Completions API
POST /v1/interactions: die Interactions API (funktioniert mit OpenAI-, Gemini- und Anthropic-Modellen)
POST /v1/messages: die Anthropic Messages API (funktioniert mit jedem Modell)

Jeder Endpunkt akzeptiert auch das optionale geordnete provider-Array, um die Route festzulegen; siehe Route festlegen unten. Das OpenAI SDK deckt /v1/responses und /v1/chat/completions ab. Es stellt /v1/interactions oder /v1/messages nicht zur Verfügung, daher erreichen Sie diese mit curl oder den nativen FlexInference SDKs (Python, TypeScript).

Client konfigurieren

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"

`start_within` übergeben

start_within teilt FlexInference mit, wie lange es warten darf, bis die Anfrage beginnt, Ergebnisse zurückzugeben. Verwenden Sie eine Dauer wie 00h-01m-00s für eine Minute. Eine Dauer startet den flex-Wettlauf: Der Planer versucht, innerhalb dieses Budgets einen günstigeren flex-Tier zu nutzen, und wechselt dann zu standard, wenn flex nicht rechtzeitig starten kann. Die OpenAI SDKs typisieren start_within nicht, daher übergeben Sie es in Python mit extra_body und in Node mit einem untypisierten Anfrageobjekt.

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

Eine vollständige Liste der Werte finden Sie unter Deadline routing.

Das flex-Ergebnis lesen

Lesen Sie service_tier im Antworttext sowie die x-flexinference-flex-*-Antwortheader. x-flexinference-flex-applied gibt an, ob flex die Antwort bereitgestellt hat. x-flexinference-flex-reason liefert das maschinenlesbare Ergebnis, einschließlich flex_committed und flex_lost_race. Eine Dauer, die keinen flex-Wettlauf ausführen kann, gibt 400 flex_unsupported_for_anthropic oder 400 flex_model_not_capable zurück. Unter Deadline routing erfahren Sie, wie Sie die Header lesen, und unter Errors finden Sie die vollständige Liste.

Streaming

Setzen Sie stream: true und verarbeiten Sie Ereignisse wie bei OpenAI. Streaming ändert das Routing nicht. FlexInference legt sich zuerst auf einen Tier fest und streamt dann Tokens, nachdem dieser Tier zu antworten beginnt.

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 begrenzt den Startzeitpunkt der Anfrage, nicht die gesamte Generierungszeit. FlexInference hält die HTTP-Antwort zurück, bis ein Tier zugesagt hat. Nachdem flex zugesagt hat, wird die Anfrage vollständig ausgeführt; FlexInference wechselt eine zugesagte Anfrage nicht zu standard, nur weil die Generierung langsam ist. Stellen Sie Ihr Client-Timeout so ein, dass es das Wartefenster plus die Zeit abdeckt, die das Modell zum Antworten benötigt. Das OpenAI SDK hat standardmäßig ein Timeout von 10 Minuten, was der längsten zulässigen start_within-Dauer entspricht. Wenn die Generierung gegen Ende eines langen Fensters beginnen kann, erhöhen Sie das Timeout über den Standardwert hinaus. Ein kürzeres Timeout kann die Anfrage abbrechen, bevor FlexInference ein Ergebnis zurückgibt. Siehe 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
});

Die nativen FlexInference SDKs (Python, TypeScript) handhaben dies automatisch. Sie dimensionieren die Wartezeit auf die erste Antwort anhand von start_within, begrenzen blockierte Streams mit einem Idle-Timeout und lassen Streams ohne Gesamtbegrenzung, damit lange Antworten abgeschlossen werden können. Nicht-Streaming-Aufrufe behalten ein Gesamtbudget bei. Jedes Timeout ist auf Client-Ebene und pro Anfrage konfigurierbar.

Wiederholung temporärer Upstream-Fehler

Fügen Sie ein optionales retry-Objekt hinzu, um den Tier, der Ihre Anfrage bedient, erneut aufzurufen, wenn dieser mit einem temporären 429 oder 5xx nicht startet. Übergeben Sie es auf die gleiche Weise wie 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 reicht von 1 bis 5, backoff ist "exponential" (Standard) oder "linear", und jitter ist standardmäßig true. Die Wiederholung erfolgt nur, bevor die Antwort zugesagt wird, berücksichtigt den Retry-After-Header des providers und wird mit den eigenen Wiederholungsversuchen Ihres Client-SDKs kombiniert. Unter Deadline routing finden Sie das vollständige Verhalten und den x-flexinference-retries-Antwortheader.

Route festlegen

Ein optionales geordnetes provider-Array legt fest, welche provider-Route Ihre Anfrage bedient. Dies gilt für jeden Endpunkt: /v1/responses, /v1/chat/completions, /v1/interactions und /v1/messages. Element 0 ist die primäre Route und das einzige flex-Gate; die Elemente 1 bis n bilden die Fallback-Kette für dasselbe Modell, die der Reihe nach versucht wird, wenn eine Route temporär fehlschlägt. Wenn Sie es weglassen, verwendet FlexInference die native Route des Modells. Übergeben Sie es auf die gleiche Weise wie start_within. Jede von Ihnen benannte Route benötigt zuerst ihren konfigurierten Schlüssel. Ein fehlender Schlüssel gibt einen 400-Fehler für diese Route zurück und fällt niemals auf die nächste zurück. Fügen Sie daher den Schlüssel jeder Route im Dashboard hinzu, bevor Sie sie benennen. Siehe 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 und anthropic sind direkte Routen. vertex (Gemini) und bedrock (Claude) sind Cloud-Routen, die dasselbe Modell auf Google Vertex AI und Amazon Bedrock bereitstellen; jede benötigt den eigenen BYOK-Schlüssel dieser Cloud. Ein ungültiges Array gibt 400 invalid_provider_chain zurück, eine Route, die das Modell nicht bedienen kann, gibt 400 provider_model_mismatch zurück, und eine Dauer start_within mit einer Cloud-Route zuerst gibt 400 flex_unsupported_on_cloud zurück. Die nativen FlexInference SDKs typisieren provider und prüfen dessen Form lokal, bevor die Anfrage Ihren Prozess verlässt; das OpenAI SDK typisiert es nicht, daher übergeben Sie es über extra_body oder ein untypisiertes Objekt. Unter provider routing finden Sie die Matrix der gültigen Ketten.

Chat Completions

Chat Completions verwendet dieselben start_within-Regeln. Eine Dauer startet den flex-Wettlauf, wenn die Anfrage über kanonische Responses geroutet werden kann. OpenAI Chat-Anfragen werden über kanonische Responses geroutet, es sei denn, ein nativer Chat-Parameter erfordert ein OpenAI Chat-Passthrough; nur native Chat-Parameter können nicht mit einer Dauer start_within kombiniert werden.

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

Der Interactions-Endpunkt ist ein weiteres Aufruferformat für OpenAI-, Gemini- und Anthropic-Modelle. start_within wird auf die gleiche Weise angewendet. Senden Sie input als String, ein Content-Array von Teilen oder eine Multi-Turn-Schrittliste. system_instruction, tools und response_format werden auf dieselben Upstream-Funktionen abgebildet.

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

Die Antwort ist ein interaction-Objekt. Die Ausgabe befindet sich in steps. usage teilt die Token-Anzahl auf input, output, thought, cached, tool-use und total auf.

{
  "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 ist requires_action, wenn ein Schritt ein function_call ist, incomplete, wenn die Ausgabe abgeschnitten wird, failed bei einem Fehler und completed ansonsten. generation_config.thinking_level wird auf reasoning.effort abgebildet. Zusätzliche generation_config.*-Schlüssel werden bei Gemini-Modellen durchgereicht. Bei Nicht-Gemini-Modellen führt jeder nicht abgebildete generation_config.*-Schlüssel zu einem Fehler mit unsupported_generation_config. Ein vom Aufrufer bereitgestellter service_tier wird mit service_tier_not_allowed abgelehnt; siehe Errors. FlexInference leitet die Tier-Auswahl von start_within ab. Wenn Sie service_tier senden, schlägt die Anfrage mit service_tier_not_allowed fehl. Entfernen Sie das Feld und drücken Sie den Tier über start_within aus. Unter Errors finden Sie die vollständige Liste und Beispiel-Bodies.

Messages

Der Messages-Endpunkt verwendet die Anthropic Messages Anfrage- und Antwortform. Er funktioniert mit jedem Modell, da FlexInference über die kanonische Form übersetzt. start_within ist erforderlich. Anthropic erfordert max_tokens; FlexInference leitet es weiter, wenn Sie es setzen, und synthetisiert keinen Standardwert, wenn Sie es weglassen. Senden Sie messages als {role, content}-Turns, wobei content ein String oder ein Array von Content-Blöcken ist. system, tools, tool_choice und thinking werden auf dieselben Upstream-Funktionen abgebildet.

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

Die Antwort ist ein Anthropic message-Objekt. Die Ausgabe befindet sich in content als text-, thinking- und tool_use-Blöcke. usage.service_tier ist der bediente Tier, entweder flex oder 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 ist end_turn bei normalem Abschluss, max_tokens bei Trunkierung, tool_use, wenn das Modell ein Tool aufruft, und refusal, wenn es ablehnt. thinking wird pro Modell auf reasoning.effort abgebildet. Bei Claude-Modellen werden native Anthropic-Felder wie top_k, stop_sequences, cache_control-Blöcke, Zitate und document- oder file-Content-Blöcke durchgereicht. Bei OpenAI- oder Gemini-Modellen werden document- und file-Content-Blöcke mit base64-Quellen in kanonische input_file übersetzt und nicht abgelehnt. Remote-URL-Dokumente hängen weiterhin von der Unterstützung des jeweiligen Ziel-providers ab. Andere Anthropic-native Felder, einschließlich top_k, stop_sequences, cache_control-Blöcke und Zitate, schlagen providerübergreifend mit unsupported_parameter fehl. Ein vom Aufrufer bereitgestellter service_tier schlägt immer mit service_tier_not_allowed fehl; siehe Errors.

Alles andere funktioniert unverändert

Tool Calling, strukturierte Ausgaben (response_format), Vision und Reasoning werden an den ausgewählten provider weitergeleitet. Verwenden Sie die normalen Felder des providers für diese Funktionen.

Chat-native Parameter werden bei OpenAI-Modellen durchgereicht, wenn ein natives Chat-Passthrough erforderlich ist: presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, seed, stop, prediction, audio, nicht-textuelle modalities und web_search_options. Bei Gemini- oder Claude-Modellen führt das Setzen eines dieser Felder auf einen realen Wert zu einem Fehler mit unsupported_parameter. Chat Completions n > 1 schlägt immer mit unsupported_value fehl. Für die Websuche auf dem kanonischen Pfad verwenden Sie ein Responses web_search-Tool.

Erste Schritte

Konzepte

API verwenden

Häufige Fragen

Client konfigurieren

`start_within` übergeben

Das flex-Ergebnis lesen

Streaming

Timeouts

Wiederholung temporärer Upstream-Fehler

Route festlegen

Chat Completions

Interactions

Messages

Alles andere funktioniert unverändert

​Client konfigurieren

​start_within übergeben

​Das flex-Ergebnis lesen

​Streaming

​Timeouts

​Wiederholung temporärer Upstream-Fehler

​Route festlegen

​Chat Completions

​Interactions

​Messages

​Alles andere funktioniert unverändert

Client konfigurieren

`start_within` übergeben

Das flex-Ergebnis lesen

Streaming

Timeouts

Wiederholung temporärer Upstream-Fehler

Route festlegen

Chat Completions

Interactions

Messages

Alles andere funktioniert unverändert