> ## 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.

# 请求元数据

> 按需获取网关为本次请求做出的决定：实际响应的模型与模型服务方、运行模式、尝试记录以及记录下来的标签。

发送 `X-Gateway-Metadata: enabled` 请求头后，响应会多出一个顶层字段 `gateway_metadata`。不带该请求头时这个字段不存在，其余内容也完全不变，因此可以放心地按请求开启、只对部分流量开启，或只在调试时开启。该字段同时以旧名 `omnirelay_metadata` 返回，内容相同；旧请求头名 `X-OmniRelay-Metadata` 也继续接受（见[兼容性](https://omnirelay.ai/docs/cn/general/tags.md#兼容性)）。

```bash theme={null}
curl https://api.omnirelay.ai/v1/chat/completions \
  -H "Authorization: Bearer $OMNIRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Gateway-Metadata: enabled" \
  -d '{"model": "gpt-6-luna", "messages": [{"role": "user", "content": "Hello"}], "tags": {"client": "acme"}}'
```

取值不区分大小写。`enabled` 以外的任何值都视为关闭。

## 返回内容

```json theme={null}
{
  "id": "chatcmpl-6f1c…",
  "object": "chat.completion",
  "choices": [{"...": "..."}],
  "usage": {"...": "..."},
  "gateway_metadata": {
    "request_id": "6f1c…",
    "requested": "gpt-6-luna",
    "model": "gpt-6-luna",
    "provider": "OpenAI",
    "mode": "live",
    "strategy": "direct",
    "attempt": 1,
    "attempts": [{"provider": "OpenAI", "model": "gpt-6-luna", "mode": "live"}],
    "tags": {"client": "acme"}
  }
}
```

| 字段 | 含义 |
| - | - |
| `request_id` | 请求 ID，与响应头 `X-Request-ID` 相同。联系支持时提供它 |
| `requested` | 你请求的模型 ID |
| `model`、`provider` | 实际响应本次调用的模型及其模型服务方 |
| `mode` | `live` 表示调用了真实模型服务方 |
| `strategy` | 模型的解析方式。目前每个模型只有一个渠道，因此恒为 `direct` |
| `attempt`、`attempts` | 最终响应的是第几次尝试，以及全部尝试。目前还没有故障转移，因此只有一次 |
| `tags` | 合并 Key 默认标签、请求头和请求体之后，本次调用实际记录的[标签](https://omnirelay.ai/docs/cn/general/tags.md)；没有时为 `{}` |
| `deprecated_header` | 仅当请求同时带有 `X-OmniRelay-Tags` 或 `X-OmniRelay-Metadata` 和值不同的现名请求头时出现：被忽略的旧请求头名 |

保留 `strategy`、`attempt` 和 `attempts` 是为了在以后加入路由与故障转移时，返回结构不必改变。它们只报告实际发生的情况，不代表计划。

## 流式响应

`stream: true` 时，元数据随**第一个**数据块返回，因为模型和模型服务方在生成任何 Token 之前就已确定。后续数据块不会重复携带。

## 控制台

**模型体验**页面中的 API 调试工具总是请求元数据，因此不带请求头，它的响应区也会显示这个字段。


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