选择协议与模型能力

从任务选择接口，区分模型可见、接口可用与功能支持。

先确定要完成的任务，再向部署管理员确认模型 ID、请求协议及所需能力。模型列表用于发现当前密钥可见的模型；模型出现在列表中，不代表它支持本文所有接口或参数。

​

按任务选择接口

任务	起点	需要确认
文本问答、多轮对话	Chat Completions 与多轮对话	消息角色、上下文限制和历史维护方式
已使用 Responses 的应用	Responses	当前渠道的 Responses 支持及具体工具能力
逐步显示文字	流式输出	SSE 事件格式、完成标记和代理缓冲
调用自己的函数	工具调用	工具参数、结果关联与应用侧执行策略
返回固定结构的数据	结构化输出	JSON / JSON Schema 模式与客户端校验
读图回答问题	图片理解	对话模型能否接收图片及支持的输入格式
生成或编辑图片	图片生成与编辑	专用图片模型、编辑能力和输出形式
生成语音	语音合成	音色、音频格式和语言支持
音频转文字或翻译	转写与翻译	上传限制、转写与翻译各自支持的模型
创建视频并等待结果	视频任务	可用渠道、任务生命周期和下载能力
语义检索与知识库问答	Embeddings、Rerank、RAG	独立的向量、重排和对话模型，以及兼容的编码方式

这是本站已有指南的选用入口，不是模型供应商能力清单。模型名称包含 chat、vision 或其他字样也不能替代实际能力确认。

​

Chat Completions 与 Responses 不可直接换路径

部分	Chat Completions	Responses
常用输入	messages	input，可结合 instructions
常用输出	choices[].message	output 条目；SDK 提供文本提取辅助
文本增量	choices[].delta.content	response.output_text.delta
完成判断	检查 finish_reason	检查 status 或最终事件

切换接口时同步修改请求体、工具结果结构、响应读取和流式完成判断。不要只把 URL 从 /chat/completions 替换为 /responses，也不要假设网关在所有渠道都能完成等价转换。服务端保存会话、内置工具及资源管理能力须单独确认；本站示例不承诺这些能力在所有部署可用。

​

最小验证顺序

1. 按地址与请求约定确认实际 API 地址，并用同一密钥查询模型。
2. 使用对应指南的最小请求，不同时加入工具、图片或结构化输出等多个选项。
3. 检查业务完成状态和输出内容，而不只检查 HTTP 200。
4. 逐项启用所需能力，每次保留请求时间、模型 ID 和非敏感错误信息，方便对照部署日志。
5. 再验证断流、失败和重试策略；不要把客户端自动重试当作能力探测方法。

​

常见误解

• SDK 有这个方法，所以网关一定支持。 SDK 可以暴露本站范围之外的接口。请以本站API 概览和部署实际能力为准。
• 同一模型能生成图片，就能编辑图片。 输入、编辑、生成属于不同能力，需要分别验证。
• JSON 能解析，就满足业务要求。 还要校验字段类型、值域和业务约束，并处理拒绝及未完成响应。
• 检索排名第一，就足以回答。 仍需检查资料是否相关、是否有权使用以及答案是否有依据，见 RAG 指南。

请求失败时按错误与重试排查。不要通过任意换模型掩盖协议或参数不兼容。

​

原生协议与流式工具

Claude Messages与 Gemini generateContent提供独立的原生协议接入示例。需要组装工具参数分片并执行函数时，见 Chat / Responses 流式工具调用。

原生协议的可运行 SSE 与工具闭环见 Claude和 Gemini，包含完成校验与签名保留。

​

查询单个模型

已知模型 ID 时，可运行 examples/model.py。它检查 HTTP 200 中的业务错误；模型不存在或不可见时非零退出，不打印完整错误载荷。先按 Python 指南安装依赖，配置同一部署的地址、令牌和模型。路径编码限制见单模型参考。

export API_BASE_URL="https://gateway.example.com/v1"
export API_KEY="YOUR_API_KEY"
export API_MODEL="YOUR_MODEL_ID"
.venv/bin/python examples/model.py

import os
from urllib.parse import quote
from openai import OpenAI, APIConnectionError, APIStatusError

model = os.environ["API_MODEL"]
if not model.strip():
    raise SystemExit("API_MODEL must not be empty.")
with OpenAI(base_url=os.environ["API_BASE_URL"].rstrip("/"),
            api_key=os.environ["API_KEY"], timeout=60.0, max_retries=0) as client:
    try:
        result = client.get(f"/models/{quote(model, safe='')}", cast_to=dict)
        # This gateway can return a model_not_found error inside HTTP 200.
        if not isinstance(result, dict) or result.get("error"):
            raise ValueError("Model lookup failed.")
        if result.get("id") != model or result.get("object") != "model":
            raise ValueError("Unexpected model metadata.")
        print(result["id"])
    except APIStatusError as error:
        raise SystemExit(f"Request failed (HTTP {error.status_code}). Check model visibility and URL encoding.")
    except APIConnectionError:
        raise SystemExit("Connection failed. No automatic retry.")
    except (ValueError, TypeError, AttributeError):
        raise SystemExit("Model lookup failed. Check the model list with the same key.")

Read in English

模型路由 · 限流与重试 · 请求观测 · AI SDK

提示词缓存 · 推理模型 · 上下文管理

​

Gemini 原生工具

在目标渠道逐项确认 googleSearch、urlContext、codeExecution。模型可发现、支持函数调用或接受工具字段，都不能证明内置工具实际执行。需要分别检查引用、URL 状态或执行结果证据。