SDK 和 API 使用

FlexInference 接受与 OpenAI 兼容的请求。保留官方 OpenAI SDK 或 curl，将基础 URL 设置为 FlexInference，使用您的 flex_live_ 密钥进行身份验证，并在每个请求中发送必需的 start_within 字段。如果省略该字段，您将收到 400 missing_start_within 错误。

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

FlexInference 支持四个 POST 端点，并将每个调用者请求结构转换为规划器选择的提供商接口：

POST /v1/responses：Responses API
POST /v1/chat/completions：Chat Completions API
POST /v1/interactions：Interactions API（适用于 OpenAI、Gemini 和 Anthropic 模型）
POST /v1/messages：Anthropic Messages API（适用于任何模型）

每个端点还接受可选的有序 provider 数组来固定路由；请参阅下面的固定路由。 OpenAI SDK 支持 /v1/responses 和 /v1/chat/completions。它不暴露 /v1/interactions 或 /v1/messages，因此请使用 curl 或 FlexInference 原生 SDK（Python、TypeScript）访问这些端点。

配置客户端

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`

start_within 告诉 FlexInference 请求开始返回数据前可以等待多长时间。使用 00h-01m-00s 这样的持续时间表示一分钟。持续时间会启动 flex 竞速：规划器会在该预算内尝试更经济的 flex 层级，如果 flex 无法及时启动，则会升级到 standard 层级。 OpenAI SDK 不对 start_within 进行类型检查，因此在 Python 中通过 extra_body 传递，在 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"
  }'

有关所有可用值，请参阅截止时间路由。

读取 flex 结果

读取响应体中的 service_tier 以及 x-flexinference-flex-* 响应头。x-flexinference-flex-applied 指示响应是否由 flex 提供。x-flexinference-flex-reason 提供机器可读的结果，包括 flex_committed 和 flex_lost_race。无法运行 flex 竞速的持续时间会返回 400 flex_unsupported_for_anthropic 或 400 flex_model_not_capable。有关如何读取这些头信息，请参阅截止时间路由，有关完整列表，请参阅错误。

流式传输

设置 stream: true 并像使用 OpenAI 一样消费事件。流式传输不会改变路由。FlexInference 首先确定一个层级，然后在该层级开始响应后流式传输 token。

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

超时

start_within 限制的是请求开始的时间，而不是总生成时间。FlexInference 会一直持有 HTTP 响应，直到某个层级确定。一旦 flex 确定，它将运行至完成；FlexInference 不会因为生成速度慢而将已确定的请求切换到 standard 层级。请将您的客户端超时时间设置为覆盖等待窗口以及模型响应所需的时间。 OpenAI SDK 默认超时时间为 10 分钟，这与允许的最长 start_within 时间相匹配。如果生成可能在较长窗口的末尾开始，请将超时时间提高到默认值以上。较短的超时时间可能会在 FlexInference 返回结果之前取消请求。请参阅 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
});

FlexInference 原生 SDK（Python、TypeScript）会自动处理此问题。它们根据 start_within 调整首次响应的等待时间，使用空闲超时限制停滞的流，并对流不设总限制，以便长时间的响应可以完成。非流式调用会保留一个总预算。每个超时都可以在客户端和每个请求中配置。

重试瞬时上游故障

当您的请求因瞬时 429 或 5xx 错误而未能启动时，添加一个可选的 retry 对象以重新尝试服务您请求的层级。传递方式与传递 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 的范围是 1 到 5，backoff 是 "exponential"（默认）或 "linear"，jitter 默认为 true。重试仅在响应确定之前进行，会遵守提供商的 Retry-After 头，并与您的客户端 SDK 自身的重试机制叠加。有关完整行为和 x-flexinference-retries 响应头，请参阅截止时间路由。

固定路由

可选的有序 provider 数组用于固定哪个提供商路由服务您的请求。它适用于所有端点：/v1/responses、/v1/chat/completions、/v1/interactions 和 /v1/messages。元素 0 是主路由和唯一的 flex 门控；元素 1 到 n 是相同模型的备用链，当某个路由瞬时失败时按顺序尝试。如果省略，FlexInference 将使用模型的原生路由。传递方式与传递 start_within 相同。您命名的每个路由都需要先配置其密钥。如果缺少密钥，该路由将返回 400 错误，并且不会回退到下一个路由，因此在命名每个路由之前，请在仪表板中添加其密钥。请参阅提供商路由。

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 和 anthropic 是直接路由。vertex (Gemini) 和 bedrock (Claude) 是云路由，它们在 Google Vertex AI 和 Amazon Bedrock 上提供相同的模型；每个都需要该云服务自己的 BYOK 密钥。无效数组会返回 400 invalid_provider_chain，无法服务模型的路由会返回 400 provider_model_mismatch，而以云路由开头的持续时间 start_within 会返回 400 flex_unsupported_on_cloud。FlexInference 原生 SDK 会对 provider 进行类型检查并在请求离开您的进程之前本地检查其形状；OpenAI SDK 不对其进行类型检查，因此请通过 extra_body 或无类型对象传递。有关有效链矩阵，请参阅提供商路由。

聊天补全

Chat Completions 使用相同的 start_within 规则。当请求可以通过规范 Responses 路由时，持续时间会启动 flex 竞速。OpenAI Chat 请求会通过规范 Responses 路由，除非原生 Chat 参数需要 OpenAI Chat 直通；仅限原生的 Chat 参数不能与持续时间 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 端点是 OpenAI、Gemini 和 Anthropic 模型的另一种调用者格式。start_within 的应用方式相同。将 input 作为字符串、内容部分数组或多轮步骤列表发送。system_instruction、tools 和 response_format 映射到相同的上游功能。

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

响应是一个 interaction 对象。输出位于 steps 中。usage 将 token 计数分为输入、输出、思考、缓存、工具使用和总计。

{
  "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": "..." }] }
  ]
}

当步骤为 function_call 时，status 为 requires_action；当输出被截断时为 incomplete；出错时为 failed；否则为 completed。generation_config.thinking_level 映射到 reasoning.effort。额外的 generation_config.* 键在 Gemini 模型上会直通。在非 Gemini 模型上，任何未映射的 generation_config.* 键都会因 unsupported_generation_config 而失败。调用者提供的 service_tier 会因 service_tier_not_allowed 而被拒绝；请参阅错误。 FlexInference 从 start_within 派生层级选择。如果您发送 service_tier，请求将因 service_tier_not_allowed 而失败。请移除该字段并通过 start_within 来表达层级。有关完整列表和示例响应体，请参阅错误。

消息

Messages 端点使用 Anthropic Messages 请求和响应结构。它适用于任何模型，因为 FlexInference 通过规范形式进行转换。start_within 是必需的。Anthropic 要求 max_tokens；当您设置它时，FlexInference 会转发它，而当您省略它时，FlexInference 不会合成默认值。将 messages 作为 {role, content} 轮次发送，其中 content 是字符串或内容块数组。system、tools、tool_choice 和 thinking 映射到相同的上游功能。

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

响应是一个 Anthropic message 对象。输出位于 content 中，作为 text、thinking 和 tool_use 块。usage.service_tier 是服务的层级，可以是 flex 或 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，截断时为 max_tokens，模型调用工具时为 tool_use，拒绝时为 refusal。thinking 映射到每个模型的 reasoning.effort。在 Claude 模型上，原生 Anthropic 字段，例如 top_k、stop_sequences、cache_control 块、引用以及 document 或 file 内容块会直通。在 OpenAI 或 Gemini 模型上，带有 base64 源的 document 和 file 内容块会转换为规范的 input_file 并且不会被拒绝。远程 URL 文档仍然取决于目标提供商自身的支持。其他 Anthropic 原生字段，包括 top_k、stop_sequences、cache_control 块和引用，在跨提供商时会因 unsupported_parameter 而失败。调用者提供的 service_tier 总是会因 service_tier_not_allowed 而失败；请参阅错误。

其他一切保持不变

工具调用、结构化输出 (response_format)、视觉和推理会直通到所选的提供商。请使用提供商的常规字段来实现这些功能。

当需要原生 Chat 直通时，Chat 原生参数会在 OpenAI 模型上直通：presence_penalty、frequency_penalty、logit_bias、logprobs、top_logprobs、seed、stop、prediction、audio、非文本 modalities 和 web_search_options。在 Gemini 或 Claude 模型上，将这些字段中的任何一个设置为实际值都会因 unsupported_parameter 而失败。Chat Completions n > 1 总是会因 unsupported_value 而失败。对于规范路径上的网络搜索，请使用 Responses web_search 工具。

快速开始

概念

使用 API

常见问题

配置客户端

传递 `start_within`

读取 flex 结果

流式传输

超时

重试瞬时上游故障

固定路由

聊天补全

交互

消息

其他一切保持不变

​配置客户端

​传递 start_within

​读取 flex 结果

​流式传输

​超时

​重试瞬时上游故障

​固定路由

​聊天补全

​交互

​消息

​其他一切保持不变

配置客户端

传递 `start_within`

读取 flex 结果

流式传输

超时

重试瞬时上游故障

固定路由

聊天补全

交互

消息

其他一切保持不变