接入排障与常见问题

按症状定位地址、协议、状态和结果处理问题。

排障时先用同一地址、令牌、模型的最小请求复现，再逐项恢复业务参数。错误与重试解释状态码；本页补充跨接口问题。

症状	优先检查	下一步
返回 HTML 或页面 404	是否请求到了网站根路径；是否重复 /v1	对照地址约定，记录实际方法与 URL
模型列表正常，生成失败	模型是否支持当前协议与参数、当前路由是否可用	去掉工具/图片等扩展，再逐个验证
模型详情 HTTP 200 但没有 id	是否包含 error	按详情参考处理业务失败
SDK 尝试上传 Files 后失败	集成框架是否自动调用了未实现端点	改用端点直接支持的输入方式，见支持范围
流式内容一次性出现	代理缓冲、压缩、前端是否累计全文才渲染	比较直连网关与经过代理的同一请求
文本输出为空或中断	拒答、工具调用、推理项、长度截断或非完成状态	使用对应协议的解析器，见流式指南
工具参数 JSON 不完整	是否在增量阶段就解析或执行	按 index / call_id 组装，确认完成后执行
原生多轮工具报签名错误	是否丢掉 thinking、thoughtSignature 或原始内容块	保留完整历史，不重建不透明签名
压缩后上下文丢失	是否只保留了 compaction 项、追加了旧历史、切换了渠道	按压缩指南保留整段输出窗口
后台响应查询 404	ID 是否来自本平台插件任务、用户/项目是否匹配、结果是否仍保留	使用原请求的身份并核对任务状态，勿自动重建任务
审核没有 results	渠道是否按文本格式重建响应	检查审核适配限制
RAG 引用不存在或答案无依据	候选 index 映射、资料权限与引用校验	使用RAG 指南逐阶段排查
媒体下载失败	任务是否完成、URL 是否过期、鉴权或 Range 是否支持	区分任务状态与下载状态，不直接重新生成

​

常见问题

能直接替换官方 SDK 的 Base URL 吗？ 对支持的同协议端点通常从这里开始，但应显式配置模型并检查框架隐藏的资源调用。迁移清单列出需要一起调整的部分。

为什么不能给所有接口统一一个输出解析器？ Chat 使用 choices，Responses 使用 output，Claude 使用内容块，Gemini 使用 candidates，媒体还可能返回字节或异步任务。HTTP 状态处理可复用，业务完成与内容提取必须按协议区分。

断线后可以直接重试吗？ 先判断请求是否可能已被接收、有无部分输出或任务 ID。任务有 ID 就先查询；结果不确定时按业务策略处理重复风险。本站不承诺全局幂等键。

本地示例测试通过意味着模型可用吗？ 不意味着。模拟测试检查客户端协议和失败路径；真实权限、模型能力、生成质量与密文可回放性仍需目标服务验收。

​

提供有效排障信息

提交以下非敏感信息给部署维护者：发生时间及时区、端点与方法、模型、SDK 版本、HTTP 状态、完成状态、网关请求 ID（若有）、经过脱敏的最小参数结构、预期与实际行为。不要发送令牌、Cookie、签名 URL、完整媒体或用户私密内容。复现步骤尽量减少请求次数。

Read in English

​

多模态与参数兼容问题

症状	原因与处理
录音已 Base64 编码仍报错	Chat input_audio.data 使用纯 Base64 与真实 format；不要加 Data URL 前缀。WAV 标记不证明采样率、时长和编码满足模型要求
转写成功，Chat 音频失败	两个端点对应不同模型能力；先确认音频 Chat 模型，再按 音频输入 发送 JSON
视频生成可用，但无法分析视频	生成与理解是不同能力；使用支持视频的原生 Gemini 模型，见 视频理解
Gemini SDK 先调用 upload/files 后 404	框架自动上传不在已核查网关路由中；使用受支持的小文件 inlineData，或让部署方确认独立文件方案，不无限重试
上游示例的 video_url 对象失效	当前 Chat 内容解析器只读取字符串分支；原始转发与转换不同，不强行复制 OpenRouter 形状
413 或媒体请求中途失败	Base64 扩大体积；检查代理、网关、上游各层大小和时长限制。缩小或正确转码；改扩展名不改变编码
浏览器能打开 URL，模型却读不到	服务端没有浏览器 cookies；签名、跳转、过期、网络和账号权限都可能影响访问。不要把网关密钥附到媒体链接
prediction 报不支持或没有加速	核对模型、原生 Chat 路径、组合参数；转 Responses 没有映射，统计缺失也不证明零接受，见 预测输出
SDK 拒绝一个文档字段	可能是 SDK 版本或方法的类型限制；用对应 HTTP 示例隔离问题。绕过客户端类型检查不代表上游就支持

​

请求生命周期常见问题

点“停止”是否一定停止服务端任务？ 客户端中止只说明不再等待或读取；不能证明上游停止、任务撤销或不会计费。不要把关闭 SSE 当作通用取消 API。已知任务 ID 应先查询状态，本项目也没有统一 Responses cancel 入口。

为什么复制官方示例仍多出接口错误？ 检查 SDK 的默认方法、资源上传、历史检索和自动重试。responses.create、Chat、Files、Interactions 不是同一个入口；按 迁移检查 使用本站已列出的端点。

参数已发出为什么没有效果？ 区分 SDK 是否序列化、DTO 是否表达、转换是否映射、渠道是否覆盖/过滤、上游是否支持。用最小请求逐项添加参数；保留非敏感诊断信息，参见 参数过滤。

​

工具策略与 JSON 常见问题

问题	核查方式
写了 strict 仍收到非法参数	当前函数工具跨 Chat/Responses 转换未复制 strict；确认实际协议路径，并始终执行应用校验
required 后模型一直调用工具	继续每轮 required 可能持续要求调用；工具结果返回后，在只需最终答案时切换 none 或合适策略，并设置轮数上限
禁用并行仍收到多个调用	不代表可安全执行；先验证整个调用列表，失败后不要执行部分工具或自动重放
指定函数不生效	Chat 的名称嵌套在 function，Responses 名称同层；检查 SDK 序列化、转换与模型支持
JSON.parse 成功却业务报错	JSON 模式不保证字段、枚举和类型，检查 null/缺失、整数/字符串和额外字段
一直收到空白或 JSON 截断	提示需明确要求 JSON，检查格式字段、模型与完成状态；不要拼接重试输出或补括号后当作成功
第二轮失败是否重做工具	工具可能已经执行；保留匹配的调用及结果，按应用恢复策略处理，避免重复改变数据

工具控制示例 · JSON 校验示例

​

Gemini 启用工具后只有文本，没有执行证据

启用内置工具允许模型使用，不会强制每次提示都执行。按工具检查 groundingMetadata、urlContextMetadata 或 codeExecutionResult。如果业务要求实际使用工具，缺少证据时应停止，不应把直接回答悄悄展示成搜索、抓取或执行后的结果。

​

搜索引用指向错误的字符

Gemini grounding 的片段偏移指向原始 part 中的 UTF-8 字节，endIndex 不包含末端字节。对中文和 emoji 使用 JavaScript 字符串切片或先拼接 part，容易发生错位。保留 partIndex 与来源顺序，在渲染前验证字节边界和 groundingChunkIndices。内置工具示例 展示单个非流式候选的处理。

​

URL 读取失败或代码执行报告错误

检查每项 URL 读取状态；付费墙、不安全 URL、重定向到其他 URL 或缺少元数据，都不代表已确认访问。代码执行可能失败或超时，但 HTTP 仍是 200。检查 outcome 和配对的代码/结果 part。示例遇到任何失败执行就停止，绝不在本地运行生成代码。自定义函数结果属于函数调用循环，不属于 codeExecutionResult。

​

新版 Gemini SDK 示例使用不支持的路由或丢失工具状态

选择 generateContent 兼容示例，不使用 Interactions 或 Files 管理调用。原生 JSON 使用 camelCase；将 Python snake_case 直接作为协议负载可能在网关 DTO 中丢失字段。原始响应元数据可能保留，但回放时较新的未知请求字段仍可能丢失。启用多轮工具组合前核对实际 DTO 与渠道，见原生工具范围。