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

# 接入排障与常见问题

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

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

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

## 常见问题

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

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

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

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

## 提供有效排障信息

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

[Read in English](/en/guides/troubleshooting)

## 多模态与参数兼容问题

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

## 请求生命周期常见问题

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

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

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

## 工具策略与 JSON 常见问题

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

[工具控制示例](/zh/guides/tool-controls) · [JSON 校验示例](/zh/guides/json-mode)

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

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

## 搜索引用指向错误的字符

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

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

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

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

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


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