ToAPIs

gemini-3.5-flash 完整解析（Markdown）

返回模型解析页

gemini-3.5-flash API 模型解析指南

快速结论

  • 官方能力包括 1M 上下文窗口、最高 64K 输出，以及函数调用、结构化输出、搜索工具和代码执行支持。
  • 相比传统轻量 Flash，更适合复杂问答、代码生成、长文档处理和 Agent 工作流。
  • 推荐仍然用 OpenAI 兼容聊天接口接入，便于复用现有 SDK、SSE 流式输出和服务端重试逻辑。

核心能力

  • 高智能但仍保持低延迟：不是单纯的低成本补位模型，而是在 Flash 速度下承接更复杂的理解、规划和生成任务。
  • 1M 超长上下文：适合长文档摘要、代码库分析、知识整合、大提示词工作流和多轮长会话。
  • 结构化与工具化输出：支持函数调用、结构化 JSON、搜索工具和代码执行，更适合 Agent 与自动化工作流。
  • 代码与技术内容能力：适合代码解释、单测生成、重构建议、接口封装和技术文档初稿。
  • OpenAI 兼容迁移：可复用 Chat Completions 风格请求体，降低从 GPT/Claude 兼容链路切换的成本。
  • 实时流式交互：支持 SSE 流式返回，适合聊天界面、终端助手和 IDE Copilot 类体验。

适用场景

  • 需要比传统轻量模型更强的理解、推理和代码能力，但又不想牺牲太多响应速度时。
  • 需要长上下文处理，例如大文档问答、代码库分析、长会话记忆或检索增强问答。
  • 需要结构化 JSON、函数调用或搜索工具接入来构建 Agent 时。

不适用场景

  • 只做极短、极简单、极端成本敏感的批量模板任务时，可能没有必要上这一级别模型。
  • 纯图像或视频生成任务应使用对应的图像/视频专用模型。

运行特性

  • 推荐通过 POST /v1/chat/completions 走 OpenAI 兼容请求结构，便于与现有中间层对接。
  • stream=true 时返回 SSE 事件流；stream=false 时返回标准完整响应对象。
  • 若业务依赖结构化输出或工具调用，建议先用小流量验证 schema、tool choice 和异常回退逻辑。

最小请求示例

{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是资深全栈工程师，先总结方案，再给最小可运行代码。"
    },
    {
      "role": "user",
      "content": "帮我写一个 Node.js 函数：读取 CSV，过滤重复邮箱，并输出统计结果。"
    }
  ],
  "temperature": 0.2,
  "max_tokens": 500,
  "stream": false
}

最小响应示例

{
  "id": "chatcmpl_xxxxxxxx",
  "object": "chat.completion",
  "created": 1747699200,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 260,
    "total_tokens": 380
  }
}

关键参数

参数类型必填默认值范围说明
modelstring是gemini-3.5-flash-模型名称，建议使用 gemini-3.5-flash。
messagesobject[]是--按时间顺序排列的对话消息；常见角色包括 system、user、assistant。
max_tokensinteger否->=1, practical cap should be set by your app最大输出 token 数；官方能力可到 64K 输出，但实际应按场景和成本做业务约束。
streamboolean否false-是否启用 SSE 流式输出。
temperaturenumber否10-2采样温度，越低越稳定，越高越发散。
top_pnumber否10-1核采样阈值，建议不要和 temperature 同时大幅调节。
toolsobject[]否--函数或工具定义，用于工具调用和 Agent 编排。
AuthorizationHTTP Header是--Bearer 鉴权：Authorization: Bearer <YOUR_API_KEY>。

常见错误

HTTPCode触发条件修复建议重试策略
400invalid_request_error请求体缺少必填字段、messages 结构错误或参数类型不匹配。先校验 model、messages、max_tokens 以及 tools/schema 的 JSON 结构。修正请求体后重试，不建议盲重试。
401authentication_errorAuthorization 头缺失、格式错误或 API Key 无效。确认 Authorization: Bearer <YOUR_API_KEY> 格式和密钥权限。修复鉴权后重试。
429rate_limit_error请求频率、并发或当前额度命中上游限流策略。采用指数退避，并检查批量并发、上下文长度和当前配额消耗。建议 1s/2s/4s + 抖动；持续触发时收紧并发或降级任务。
500internal_error上游瞬时波动、工具执行异常或内部处理失败。记录 request id 和上下文摘要后重试，持续失败再人工排查。可短间隔重试 2-3 次。

FAQ

  1. gemini-3.5-flash 最适合哪些任务？
    它最适合需要较强理解和生成能力、但又强调吞吐和响应速度的文本与代码助手任务。
  2. 它和传统 Flash 模型有什么区别？
    核心区别是智能上限更高，不再只是轻量快速回复，更适合复杂问答、长上下文和工具化任务。
  3. 怎么最快接入到现有系统？
    优先走 OpenAI 兼容的 Chat Completions 链路，复用现有 messages、streaming 和服务端重试逻辑。
  4. 什么时候应该严格控制 max_tokens？
    长上下文、代码生成和结构化输出场景尤其要控制 max_tokens，避免响应过长、成本失控或超时。

相关 API