> ## Documentation Index
> Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型接入与请求诊断

> 确认真实模型访问、检查请求记录，并理解费用预留与结算。

核对日期：2026-10-04。客户使用 **OmniRelay API Key** 调用统一 API；客户无需创建或提交任何其他凭证。

## 确认可以调用的模型

真实服务按工作空间开通。公开目录展示、注册成功、充值或连接检查成功，都不代表模型已经获得调用权限。先使用自己的 Key 查询 `GET https://api.omnirelay.ai/v1/models`，使用返回的精确模型 ID 与 `mode: live`。

逐模型检查以下字段，不要把某个模型的设置套用到其他模型：

| 字段 | 用途 |
| - | - |
| `capabilities` | 文本、system 消息、SSE 和推理内容支持情况。 |
| `limits` | 消息、输出默认值与最大值等运行时限制。 |
| `reasoning_efforts` | 可传的推理强度；空列表时省略 `reasoning_effort`。 |
| `pricing`、`cache_pricing`、`input_tiers` | 客户基价及适用的缓存／阶梯价格。 |
| `customer_discount_bps`、`price_version` | 客户折扣比例和冻结价格版本。 |
| `reservation` | 最低、默认与最大输出对应的客户费用预留，单位微美元。 |

多数已接入文本模型最多输出 128,000 Token、默认 32,000（Gemini 3.1 Pro Preview 和 Gemini 3.6 Flash 最多 65,536）；DeepSeek V4 Pro、GLM 5.3 和 Kimi K3 默认且最多 4,096；GPT 5.4 Mini 默认 64、最多 256。SSE 并非所有模型都支持；返回推理内容也不代表可以调整推理强度。详见[模型列表](https://omnirelay.ai/docs/cn/llms/listing-models.md)和[对话补全](https://omnirelay.ai/docs/cn/llms/chat-completions.md)。

## 工作空间开通状态

控制台**总览 → 真实模型服务**显示配置状态。登录后的 `GET https://omnirelay.ai/api/me` 在 `workspace.inference` 返回以下结构；这是字段示例，不是完整响应或固定模型列表：

```json theme={null}
{
  "workspace": {
    "inference": { "status": "enabled", "models": ["gpt-6-luna"] }
  }
}
```

| status | 含义与下一步 |
| - | - |
| `not_enabled` | 尚未开通或已停止，联系支持确认范围。 |
| `activation_pending` | 开通尚未完成，充值不会自动完成开通。 |
| `awaiting_funds` | 账户配置或服务开通正在等待所需资金。 |
| `enabled` | 配置已就绪，仍需有效客户 Key、模型权限及足够可用额度。 |
| `maintenance` | 新真实请求暂时暂停，重试前检查已有记录。 |
| `action_required` | 需要平台核查，联系支持。 |
| `unavailable` | 当前配置未就绪，联系支持，不重复付款解决。 |

该状态按登录账户的工作空间展示，不按某个 API Key 的白名单筛选，也不是实时健康检查。使用特定 Key 的实际模型列表，仍需调用 `/v1/models`。`/api/me` 使用控制台会话，推理 Key 和管理密钥不能替代登录会话。

## 当前请求支持范围

* 使用文本消息；`system` 与 `developer` 是否可用以对应模型能力为准。
* `max_tokens`、`max_completion_tokens`、`max_output_tokens` 三个别名只传一个，正整数且不超过 `limits.output_tokens`；省略时采用 `limits.default_output_tokens`。
* 请求体上限为 4 MiB，最多 2,000 条消息，单个文本值最多 1,048,576 字符；模型上下文窗口仍然适用。详见[限流](https://omnirelay.ai/docs/cn/overview/rate-limits.md)。
* GPT 5.4 Mini 已支持函数工具、JSON object/schema 输出及无状态 Responses HTTP／SSE。严格工具、图片、音频、图像／视频生成及采样仍关闭。普通 JSON HTTP 响应不等于结构化生成。
* `response_format: {"type":"text"}` 可用，普通调用可以省略。不要传未列出的 `reasoning_effort` 或 `temperature` 等字段。
* 支持 SSE 时传 `stream: true`；需要客户端用量块时增加 `stream_options.include_usage: true`。网关始终收集最终用量用于结算。
* 支持推理内容时，JSON 位于 `choices[0].message.reasoning_content`，SSE 位于 `choices[0].delta.reasoning_content`。

## 预留与实际费用

发送前，网关按输入估算（请求体字节数的三分之一加 4,096 Token 固定开销，不超过所选模型已核验的输入硬上限，按未缓存输入单价）、请求输出上限及客户价格预留估算费用。短提示词也需要钱包和 Key 预算覆盖预留。若核验用量的费用超过预留（例如密集的非拉丁文字或缓存写入），仅当超出后的总额不超过预留的两倍，且钱包、Key 预算、成员限额和平台额度都足以覆盖差额时，结算时扣除差额；否则请求保持待对账。预留不是提示词的实测 Token 数，不是固定收费，也不保证请求能放入模型上下文。

收到有效最终用量后，按请求冻结价格结算并释放未用金额。`cost_microusd` 为已结算费用，除以 1,000,000 得到美元。当前请求的价格、用量和费用不能由其他模型的示例推算。详见[用量与计费](https://omnirelay.ai/docs/cn/general/usage-billing.md)。

## 请求追踪与诊断

优先保存响应头 **`X-Request-ID`**，用于联系支持及下方诊断接口。回复 JSON 的 `id` 与模型服务方追踪 ID 不应混用；存在追踪 ID 也不能证明已结算。

登录后的客户诊断接口为：

```text theme={null}
GET https://omnirelay.ai/api/developer/requests?id=<OmniRelay-Request-ID>
```

此接口使用控制台会话，不接受推理 Key。仅返回当前账户及工作空间的记录，最多最近 100 条，按时间倒序。`key` 可按调用者的 Key ID 筛选。

```json theme={null}
{
  "requests": [{
    "id": "example-request",
    "upstream_trace_id": null,
    "reservation_state": "pending",
    "held_customer_cost": 60,
    "settled_cost": null,
    "price_version": "example-price-version",
    "customer_discount_bps": 10000
  }],
  "limit": 100,
  "pending": { "count": 1, "held_microusd": 60 },
  "pending_summary_scope": "account"
}
```

这是合成字段示例，金额为微美元，不是实际模型价格。`pending` 汇总该账户全部未结算预留，即使请求记录使用 `id` 或 `key` 筛选。`upstream_trace_id` 可为空。记录保存调用元数据，不保存提示词、回复正文或凭据。

## 超时、失败与待对账

成功 SSE 以 `[DONE]` 结束；用量块的 choices 为空，需单独读取。失败流不返回成功结束标记；断开连接时也可能收不到错误事件。流开始时的 HTTP 200 不等于最终成功。

在任何输出送达前失败的调用会立即释放预留、不收费；已送达部分输出、或回答缺少有效最终用量时，可能保留预留并等待平台对账。`pending` 不代表免费，也不会触发自动退款或另一笔付费重试。关闭 SDK 自动重试，先按错误码判断（见[错误处理](https://omnirelay.ai/docs/cn/general/errors.md)）；只有确认在派发前拒绝或预留已释放，才决定是否重发。

平台会核查最终用量及费用证据，完成结算或释放。客户无需操作对账接口，对账由 OmniRelay 处理。联系支持时提供发生时间、模型 ID、Request ID 和错误码，勿提供完整 Key。详见[错误处理](https://omnirelay.ai/docs/cn/general/errors.md)及[用户手册](https://omnirelay.ai/docs/cn/user-manual.md)。

## 申请服务开通

验证后的新注册账户会在自动开通启用时进入配置队列。已有账户可在**总览 → 真实模型服务**中，使用页面提供的**申请开通**入口。该模块仅显示在总览，以状态说明进度，不列出已开通模型。账户配置可能早于付费推理就绪；进入队列、建立账户或充值，本身都不代表真实模型已经开通。刷新状态，需要核查时联系 [support@omnirelay.ai](mailto:support@omnirelay.ai)。

服务开通前即可在**模型广场**浏览平台支持的模型与价格，但所有模型均为不可用且没有调用入口；推理 Key 和管理密钥也须在开通核验完成后创建。点击信息图标只弹出详情，不离开当前页面。实际可调用模型仍需使用自己的 Key 查询 `/v1/models`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.