# 文本模型调用

> 用 Chat Completions、Responses、Messages、Gemini 四种标准协议调用文本模型。

Base URL：`https://platform.sgt.site`

文本模型使用四种标准协议。网关按渠道上游的原生协议转换请求与响应；能否服务取决于模型授权、当前渠道和本次请求需要保留的功能。

<a id="llm-api-section-1"></a>

## 端点

| 协议 | Base URL | 方法与相对路径 | 说明 |
| --- | --- | --- | --- |
| OpenAI Chat Completions | `https://platform.sgt.site` | `POST /v1/chat/completions` | 以 `messages` 提交对话，读取 `choices` 或流式增量 |
| OpenAI Responses | `https://platform.sgt.site` | `POST /v1/responses` | 以 `input` 提交输入，读取 `output` 或响应事件 |
| Anthropic Messages | `https://platform.sgt.site` | `POST /v1/messages` | 以 `messages` 提交对话，读取 `content`；请求必须带 `max_tokens` |
| Gemini | `https://platform.sgt.site` | `POST /v1beta/models/{model}:generateContent` | 流式用 `:streamGenerateContent?alt=sse`；也支持 `/v1/models/{model}:…` |

表中路径附加到网关根地址一次，示例使用当前网关地址。虚拟密钥的准备方式见[地址与鉴权](access.md)。

调用前用 `GET /v1/models` 查询这把密钥实际可用的模型 ID 和协议，再选择上表中的对应接口。该目录也包含图片、视频和 3D 模型，按[模型列表：只列出文本模型](models.md#models-text-filter)筛出文本模型。

渠道不具备转换能力、会丢失关键功能或转换质量不满足门槛时，网关在发送上游前排除该渠道，先尝试同优先级的其他渠道。这个过程不消耗上游失败重试次数，也不把渠道标记为故障。

全部候选均不适用时返回 HTTP 400：仅能力缺口为 `invalid_request`；存在关键功能损失或质量不满足时为 `convert_request_failed`。请根据错误提示调整功能或入口协议，重复提交相同请求不能解除限制。参数本身无效也会直接拒绝。

`good`、`fair` 转换路径可用，`discouraged` 默认拒绝，只能由平台按模型开启。目录中的可用协议不承诺保留所有协议独有功能：工具定义和结果、结构化输出、图片与文件输入的关键损失会拒绝；非关键调整会记录诊断。

通用 OpenAI 兼容渠道显式声明 Responses 原生时保留原生 `/responses`；仅声明 Chat 时走 Responses→Chat。`previous_response_id` 等有状态功能不能转成 Chat，`/v1/responses/compact`、`/v1/alpha/search` 需要原生 Responses 渠道。只支持 Responses 的模型仍使用原生入口。

成功响应头 `X-Heighliner-Protocol-Route` 给出本次路径（如 `messages>chat`），`X-Heighliner-Conversion-Diagnostics` 仅含本次请求转换的诊断码。被排除渠道和响应转换阶段的诊断只进入管理员日志。费用与 token 均以实际上游 usage 形成的权威账单为准。

请求超时或流式连接中断时，保留已收到的内容、用量和响应头 `X-Oneapi-Request-Id` 供核对。文本调用没有媒体任务那样的任务查询和幂等重放，重新发送是一次新的调用。

<a id="llm-api-section-2"></a>

## 鉴权与 SDK 配置

虚拟密钥的说明见[地址与鉴权](access.md)。四种协议都接受 Bearer，另可使用各协议 SDK 默认的请求头：

- OpenAI 协议：`Authorization: Bearer YOUR_VIRTUAL_KEY`。
- Anthropic 协议：`x-api-key: YOUR_VIRTUAL_KEY` 或 `Authorization: Bearer YOUR_VIRTUAL_KEY`。
- Gemini 协议：优先使用 `x-goog-api-key: YOUR_VIRTUAL_KEY`，也接受 `?key=YOUR_VIRTUAL_KEY` 或 Bearer。查询参数不写入平台访问日志。

| SDK | Base URL |
| --- | --- |
| OpenAI SDK | `https://platform.sgt.site/v1` |
| Anthropic SDK | `https://platform.sgt.site`（SDK 会自动追加 `/v1/messages`） |
| Gemini SDK（文本） | `https://platform.sgt.site`，API version 选 `v1beta` |

<a id="llm-api-section-3"></a>

## 请求示例

下面使用目录中可用的 `deepseek-flash` 演示文本请求；如果你的目录没有该型号，替换成已授权且支持所选协议的文本模型。curl 使用[地址与鉴权](access.md)中准备的 `GATEWAY_ORIGIN` 和 `KEY`，均只发送一次请求。不要把厂商前缀 `/gemini` 加到本页的文本请求上。

OpenAI Chat Completions：

```http
POST /v1/chat/completions HTTP/1.1
Host: platform.sgt.site
Authorization: Bearer YOUR_VIRTUAL_KEY
Content-Type: application/json
```

```json
{
  "model": "deepseek-flash",
  "messages": [
    {"role": "user", "content": "用一句话介绍你自己"}
  ],
  "max_tokens": 1024
}
```

Anthropic Messages：

```http
POST /v1/messages HTTP/1.1
Host: platform.sgt.site
x-api-key: YOUR_VIRTUAL_KEY
anthropic-version: 2023-06-01
Content-Type: application/json
```

```json
{
  "model": "deepseek-flash",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "用一句话介绍你自己"}
  ]
}
```

OpenAI Responses：

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/v1/responses" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "deepseek-flash",
    "input": "用一句话介绍你自己",
    "max_output_tokens": 1024
  }'
```

非流式响应中遍历 `output[]`，从 `type: "message"` 的 `content[]` 中读取 `type: "output_text"` 的 `text`；不要套用 Chat Completions 的 `choices`。`usage.input_tokens` 和 `usage.output_tokens` 表示输入、输出用量，`status` 表示本次响应是否完成。设置 `"stream": true` 后返回 SSE，应按事件读取文本增量并检查完成或错误事件，不能再把整个响应作为一个 JSON 对象解析。

Gemini 文本协议：

```bash
curl -sS -X POST "$GATEWAY_ORIGIN/v1beta/models/deepseek-flash:generateContent" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话介绍你自己"}]}
    ],
    "generationConfig": {"maxOutputTokens": 1024}
  }'
```

型号写在路径中，请求体无需再传 `model`。非流式文本位于 `candidates[].content.parts[].text`，结束原因在各候选的 `finishReason`，用量在 `usageMetadata`。文本可能分成多个 part，请按次序拼接。流式使用同一请求体，把路径末尾换成 `:streamGenerateContent?alt=sse`，并给 curl 加 `-N`；每个 SSE `data` 是一个 Gemini 响应片段。使用 SDK 的 `x-goog-api-key` 时按上节鉴权约定替换 Bearer，不同时发送两种密钥头。

<a id="llm-api-section-4"></a>

## 输出长度的默认值

本节说明企业预算主体请求的网关补入规则，单位均为输出 token，既不是实际返回量，也不是厂商规格上限。厂商原生默认与最大值另见[规格参考](llm-catalog.md)。

| 协议 | 显式限制字段（可选正整数，单位 token） | 网关在缺失时补入 |
| --- | --- | --- |
| Chat Completions | `max_tokens` 或 `max_completion_tokens`；按目标模型选择 | 两者均省略或为 null 时补 `max_tokens=8192` |
| Responses | `max_output_tokens` | 8192 |
| Gemini | `generationConfig.maxOutputTokens` | 按映射后的型号，见下表；同步与 SSE 相同 |
| Messages | `max_tokens`（必填） | 不使用本节默认补入，调用方需显式提供 |

| Gemini 映射后的型号 | 补入 token 数 |
| --- | --- |
| `gemini-3.8-flash` | 65536 |
| `gemini-3.1-flash-image`、`gemini-3-pro-image`，含对应 `-preview` 名称 | 32768 |
| `gemini-3.1-flash-lite-image` | 4096 |
| 其他型号 | 8192（平台回退值，不是厂商默认） |

只有网关实际补入时才设置响应头 `X-Enterprise-Default-Output-Tokens`，值是十进制整数文本，表示本次补入数量；未出现该头不能推断无限输出或零费用。非企业请求不走这项企业默认补入。显式数值会保留，`0` 也不会被自动改成默认，但零值是否被接受由协议/模型校验决定，不应用零表达“无限”。省略或 JSON `null` 在本默认处理器中都视为未指定；空字符串、负数和小数不是有效上限。

需要稳定上限时显式设置对应字段，满足模型和协议校验；较大的厂商规格上限不会自动覆盖网关默认。网关先补入再参与预算预估，不影响未知响应字段的兼容处理。