Create a chat completion
为提供的对话消息列表生成大语言模型补全回复。OmniCortex 全面兼容 OpenAI 标准格式，并原生扩展了 provider/model 统一路由命名空间、多通道凭证负载均衡、跨模型熔断降级（fallbacks）以及流式深度思考审计能力。
请求头 (Headers)
Authorizationstringheader Bearer Token 鉴权凭证。推荐方式，支持传入上游提供商 API Key 或 OmniCortex 虚拟密钥（以
sk-bf- 开头）。格式：Bearer <token>。 x-api-keystringheader 通过请求头传递 API 密钥。同样支持直接传入 OmniCortex 虚拟密钥。
x-bf-vkstringheader OmniCortex 虚拟密钥专属请求头，用于精细化团队组织治理、分流路由与配额限流控制。
Content-Typestringheaderrequired 请求体媒体格式，固定为
application/json。 必填参数 (Required Body Parameters)
modelstringbodyrequired 目标模型标识或统一路由别名。格式为
provider/model（例如 openai/gpt-4o、anthropic/claude-3-5-sonnet、deepseek/deepseek-chat）。 messagesarraybodyrequired 迄今为止构成对话的历史消息对象列表。每条消息包含：
role(string, 必需): 消息发送者角色，可选system、user、assistant、tool、developer。content(string | array, 必需): 消息内容，支持纯文本字符串或多模态内容块列表（包含text、image_url、input_audio、file等）。name(string, 可选): 参与者姓名，便于模型区分同角色的不同发言人。tool_call_id(string, 可选): 当角色为tool时必填，对应助手发起的工具调用 ID。tool_calls(array, 可选): 当角色为assistant时，模型生成的工具调用列表。
高可用与调度路由 (Routing & Reliability)
fallbacksarraybody 备选模型容灾列表，每个元素格式为
provider/model。当主模型遭遇速率限制（429）或上游不可用（5xx）时，网关将无感依序降级至备选模型。 采样与生成控制 (Sampling & Generation)
streambooleanbodydefault: false 是否使用 Server-Sent Events (SSE) 流式返回响应数据块。
stream_optionsobjectbody 流式响应扩展选项。包含
include_usage（设为 true 时在最后一个流分块中返回 token 用量数据）和 include_obfuscation。 temperaturenumberbodydefault: 1 采样温度，介于 0 到 2 之间。较高的值（如 0.8）会使输出更具创意与随机性，较低的值（如 0.2）则使输出更加确定与严谨。
top_pnumberbodydefault: 1 核采样阈值，介于 0 到 1 之间。模型仅考虑累积概率达到
top_p 的候选词集合。建议不要与 temperature 同时大幅调整。 max_completion_tokensintegerbody 模型在单次补全中允许生成的最大 token 数量上限（推荐用于 o1/o3 及支持 reasoning 的新一代模型）。
frequency_penaltynumberbodydefault: 0 频率惩罚系数，介于 -2.0 到 2.0 之间。正值会根据 token 在文本中已出现的频次对其进行惩罚，降低逐字重复同一段话的倾向。
presence_penaltynumberbodydefault: 0 存在惩罚系数，介于 -2.0 到 2.0 之间。正值会根据 token 是否已在文本中出现过对其进行惩罚，鼓励模型探讨新的主题。
stopstring | arraybody 停止词序列，可为单个字符串或最多包含 4 个字符串的列表。当模型输出遇到停止词时将立刻终止生成。
seedintegerbody 确定性随机种子。如果指定，系统将尽最大努力以确定性方式采样，使多次相同的请求返回几乎一致的生成结果。
工具调用与深度思考 (Tools & Reasoning)
toolsarraybody 模型可调用的工具定义列表。支持标准函数（
function）及自定义语法约束（custom），并原生支持 cache_control 提示词缓存策略。 tool_choicestring | objectbody 控制模型调用工具的行为策略。支持枚举字符串（
none、auto、required）或具体指定强制调用某函数的对象。 parallel_tool_callsbooleanbodydefault: true 是否允许模型在单次回复中并行发起多个工具调用。
reasoningobjectbody 深度思考/推理模型专属配置：
effort(string): 推理思考强度等级，可选none、minimal、low、medium、high、xhigh。max_tokens(integer): 允许思考过程消耗的最大 token 上限。
response_formatobjectbody 指定模型输出的结构格式，例如
{ "type": "json_object" } 或带有 JSON Schema 严格校验的结构化输出定义。 高级优化与扩展 (Advanced & Extensions)
predictionobjectbody 预测输出内容（仅 OpenAI 支持）。模型以此为前缀参考生成，可大幅降低长文档修改场景的响应延迟。
web_search_optionsobjectbody 联网搜索扩展配置（仅支持联网的模型）。包含
search_context_size（搜索上下文大小：low、medium、high）以及 user_location（发起端用户地理位置过滤）。 prompt_cache_keystringbody 提示词缓存键，用于跨请求精确复用历史长上下文计算结果。
prompt_cache_retentionstringbody 提示词缓存保留策略，可选
in_memory（内存即时缓存）或 24h（保留 24 小时）。 logit_biasobjectbody Token 偏置映射，用于修改特定 token 在模型采样生成中出现的似然概率。
logprobsbooleanbodydefault: false 是否返回输出 token 的对数概率信息。
top_logprobsintegerbody 介于 0 到 20 之间，指定在每个 token 位置返回最可能的前 N 个 token 的对数概率。必须先将
logprobs 设为 true。 storebooleanbodydefault: false 是否在网关端持久化存储本次补全记录，以便于后续开展离线评估、微调或蒸馏。
metadataobjectbody 附加到请求的自定义键值对元数据，可用于全链路业务追踪与自定义合规审计。
modalitiesarraybody 期望模型输出的模态列表，例如
["text"] 或 ["text", "audio"]。 userstringbody 终端用户的唯一标识符，可用于网关限流、防刷监控以及日志行为审计。
Chat Completions
HTTP / SDK
bash
curl --request POST \
--url http://localhost:8080/v1/chat/completions \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'Content-Type: application/json' \
--data '{
"model": "deepseek-v4-flash",
"messages": [
{
"role": "system",
"content": "You are a helpful and concise AI assistant."
},
{
"role": "user",
"content": "Introduce yourself in one sentence."
}
],
"temperature": 0.7,
"max_completion_tokens": 1024,
"stream": false
}'python
from openai import OpenAI
# 仅需调整 base_url 与 api_key，即可零成本迁移
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="sk-bf-your-virtual-key"
)
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful and concise AI assistant."},
{"role": "user", "content": "Hello! How does OmniCortex provide high-availability routing?"}
],
# 通过 extra_body 传入 OmniCortex 专属跨模型容灾配置
extra_body={
"fallbacks": [
"anthropic/claude-3-5-sonnet",
"deepseek/deepseek-chat"
]
},
temperature=0.7,
max_tokens=1024
)
print(response.choices[0].message.content)typescript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'http://localhost:8080/v1',
apiKey: 'sk-bf-your-virtual-key',
});
async function main() {
const completion = await client.chat.completions.create({
model: 'openai/gpt-4o',
messages: [
{ role: 'system', content: 'You are a helpful AI assistant.' },
{ role: 'user', content: 'Hello!' },
],
// @ts-ignore - 传递 OmniCortex 扩展容灾参数
fallbacks: ['anthropic/claude-3-5-sonnet'],
temperature: 0.7,
});
console.log(completion.choices[0].message.content);
}
main();Response
json
{
"id": "chatcmpl-9A8b7c6D5e4F3a2b1",
"object": "chat.completion",
"created": 1726915200,
"model": "openai/gpt-4o",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! OmniCortex provides high-availability routing through intelligent fallback chains, real-time health monitoring, and weighted round-robin load balancing across multi-provider credential pools."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 36,
"total_tokens": 64,
"prompt_tokens_details": {
"cached_read_tokens": 0,
"cached_write_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0
}
},
"extra_fields": {
"request_type": "chat_completion",
"provider": "openai",
"model_requested": "openai/gpt-4o",
"latency": 285
}
}