Gemini CLI 安装与配置

Google AI 编程助手，适合超大上下文代码任务。

请先完成「环境准备」章节，确保 Node.js 和 npm 已安装。

Linux / macOS 配置

步骤 1: 安装 Gemini CLI

npm i -g @google/gemini-cli

步骤 2: 配置环境变量

添加到 ~/.bashrc 或 ~/.zshrc：

# API 接入地址：只填写域名，不要追加 /v1beta
export GOOGLE_GEMINI_BASE_URL="https://api.icodeeasy.cc"

# 使用本站 API Key
export GEMINI_API_KEY="你的API Key"

# 推荐快速模型。也可以改为 gemini-3.1-pro-preview 等强模型
export GEMINI_MODEL="gemini-3.7-flash"

# 推荐显式使用 Gemini API v1beta
export GOOGLE_GENAI_API_VERSION="v1beta"

保存后运行 source ~/.bashrc 或 source ~/.zshrc 使配置生效。

注意：GOOGLE_GEMINI_BASE_URL 不要写成 https://api.icodeeasy.cc/v1beta，否则 Gemini CLI 会拼出 /v1beta/v1beta/models/... 导致请求路径错误。 如果 api.icodeeasy.cc 连接慢，可以把 GOOGLE_GEMINI_BASE_URL 换成 https://jp.icodeeasy.cc 或 https://sg.icodeeasy.cc，同样不要追加 /v1beta。

步骤 3: 启动 Gemini

cd your-project-folder
gemini

Windows 配置

步骤 1: 安装 Gemini CLI

npm i -g @google/gemini-cli

步骤 2: 配置环境变量（PowerShell）

# API 接入地址：只填写域名，不要追加 /v1beta
[Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://api.icodeeasy.cc", "User")

# 使用本站 API Key
[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的API Key", "User")

# 推荐快速模型。也可以改为 gemini-3.1-pro-preview 等强模型
[Environment]::SetEnvironmentVariable("GEMINI_MODEL", "gemini-3.7-flash", "User")

# 推荐显式使用 Gemini API v1beta
[Environment]::SetEnvironmentVariable("GOOGLE_GENAI_API_VERSION", "v1beta", "User")

设置后需要重新打开 PowerShell 才能生效。

如果 api.icodeeasy.cc 连接慢，可以把 GOOGLE_GEMINI_BASE_URL 换成 https://jp.icodeeasy.cc 或 https://sg.icodeeasy.cc，同样不要追加 /v1beta。

步骤 3: 启动 Gemini

新开一个 PowerShell，进入工程目录并启动：

cd your-project-folder
gemini

模型选择

常用模型：

Gemini CLI 内置的 flash 选项可能会解析到旧的 gemini-3-flash-preview。如果客户端或插件传入 gemini-3-flash，本站会自动映射到 gemini-3-flash-preview。文本模型 gemini-2.5-flash 也继续可用：自 2026-08-03 起按原名直接提供（不再透明升级到 gemini-3.6-flash），按 2.5 Flash 价格计费。

Raw API 与严格 JSON 示例

如果业务程序需要直接解析模型返回值，建议务必在 generationConfig 中配置完整的 responseJsonSchema，并同时设置 responseMimeType: application/json。仅在提示词里写“返回 JSON”，或者只设置 responseMimeType，都不足以稳定约束字段结构和 JSON 语法。

重点： responseMimeType 只声明期望的输出类型；responseJsonSchema 才负责约束字段、类型、必填项和嵌套结构。只要业务目标是拿到可解析的 JSON，就建议配置完整的 responseJsonSchema。

下面示例使用环境变量保存 API Key。请替换成你自己的 Key，不要把真实 Key 提交到代码仓库：

export ICODEEASY_API_KEY="你的API Key"

非流式：严格 JSON（推荐）

非流式 generateContent 会在模型完成后一次性返回整个响应，更适合需要完整 JSON、结构校验或写入数据库的任务。

当请求明确配置 JSON MIME 或 Schema 时，本站会在非流式响应交付前检查完整结束状态、业务文本是否为合法 JSON，以及本站支持范围内的 Schema 约束。首次结果不符合契约时，服务端会在可重试条件满足时进行一次有限自动重试；再次失败则返回可重试的服务错误，而不会把格式错误的正文当作成功结果交给业务程序。客户端仍应保留自己的 JSON 和字段校验。

curl --silent --show-error \
  "https://api.icodeeasy.cc/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: ${ICODEEASY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "systemInstruction": {
      "parts": [
        {
          "text": "只输出符合 responseJsonSchema 的 JSON，不要输出 Markdown 代码块或额外说明。"
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请评估这句话描述的发布风险：数据库迁移尚未做回滚演练。"
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.1,
      "responseMimeType": "application/json",
      "responseJsonSchema": {
        "type": "object",
        "properties": {
          "riskLevel": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          },
          "summary": {
            "type": "string"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["riskLevel", "summary", "reasons"],
        "additionalProperties": false
      }
    }
  }' \
  --output gemini-response.json

接口最外层响应本身是 Gemini 协议 JSON；真正的业务 JSON 位于 candidates[].content.parts[].text 中。安装了 jq 后，可以这样提取并验证：

jq -e '.candidates[0].finishReason == "STOP"' gemini-response.json > /dev/null

jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | (.text // "")] | join("")' \
  gemini-response.json > result.json

jq -e . result.json

如果最后一条命令报解析错误，就不要把结果交给后续业务逻辑；应记录本次响应并按业务容忍度重试。生产代码还应检查 finishReason，只有完整结束的响应才进入业务处理。

流式：SSE 严格 JSON

流式接口适合需要尽早展示内容的场景。curl -N 会关闭输出缓冲，让 SSE 数据到达后立即写出：

SSE 数据一旦发送就无法由服务端撤回，因此不具备非流式接口的“完整响应校验后再交付”能力。严格 JSON 是核心业务契约时，应优先使用上面的非流式示例。

curl -N --silent --show-error \
  "https://api.icodeeasy.cc/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: ${ICODEEASY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  --data-binary '{
    "systemInstruction": {
      "parts": [
        {
          "text": "只输出符合 responseJsonSchema 的 JSON，不要输出 Markdown 代码块或额外说明。"
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请评估这句话描述的发布风险：数据库迁移尚未做回滚演练。"
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.1,
      "responseMimeType": "application/json",
      "responseJsonSchema": {
        "type": "object",
        "properties": {
          "riskLevel": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          },
          "summary": {
            "type": "string"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["riskLevel", "summary", "reasons"],
        "additionalProperties": false
      }
    }
  }' \
  --output gemini-response.sse

SSE 中每一行 data: 后面的 Gemini 协议外壳是 JSON，但其中的 parts[].text 通常只是业务 JSON 的一个片段。不能逐条对 text 执行 JSON.parse；必须按顺序拼接所有非思考文本，流结束后再解析一次。

下面命令会忽略非 JSON 的 SSE 结束标记，拼接文本片段并验证最终结果：

sed -n 's/^data: *//p' gemini-response.sse \
  | jq -jR '
      fromjson?
      | [.candidates[]?.content.parts[]?
          | select(.thought != true)
          | (.text // "")]
      | join("")
    ' > result.json

jq -e . result.json

正式集成时应使用客户端语言的 SSE 解析库，并同时处理断流、超时、非 STOP 结束原因和 JSON 校验失败。若核心目标是稳定取得一份可机器解析的 JSON，优先使用非流式接口。

关键参数说明

本站会为部分“明确要求只输出 JSON、但漏传 MIME”的 Gemini 请求提供兼容补充，但不会从普通自然语言提示中猜测任意业务 Schema，也不会覆盖调用方已经设置的 MIME 或 Schema。为了让请求在不同模型版本和服务环境下保持一致，请始终由客户端显式发送完整约束。

即使设置了 MIME 和 Schema，生成式模型仍不能提供数学意义上的 100% 格式保证。推荐的兜底顺序是：完整 responseJsonSchema + application/json → 低温度 → 非流式完整接收 → JSON/字段校验 → 失败后有限重试。

视频分析 Demo

Gemini 模型支持视频理解输入：把视频作为 inlineData（base64）随请求一起发送，模型看完视频后按你的要求输出分析结果。常用的支持视频的模型：gemini-3.7-flash、gemini-3.6-flash。

下面是一个完整可运行的 Demo：读取本地 MP4 → 组装请求 → 非流式调用 → 提取并校验 JSON 结果。

# 0) 如果还没设置，先配置本站 API Key
export ICODEEASY_API_KEY="你的API Key"

# 1) 本地视频转 base64（macOS 用：base64 -i demo.mp4 | tr -d '\n' > demo.b64）
base64 -w0 demo.mp4 > demo.b64

# 2) 用 jq 组装请求，避免手工拼接超长 JSON
jq -n --rawfile data demo.b64 '{
  contents: [
    {
      role: "user",
      parts: [
        {text: "请观看这段视频，输出内容摘要、分镜描述和关键词，严格按 Schema 返回 JSON。"},
        {inlineData: {mimeType: "video/mp4", data: $data}}
      ]
    }
  ],
  generationConfig: {
    temperature: 0.1,
    responseMimeType: "application/json",
    responseJsonSchema: {
      type: "object",
      properties: {
        summary: {type: "string"},
        scenes: {type: "array", items: {type: "string"}},
        keywords: {type: "array", items: {type: "string"}}
      },
      required: ["summary", "scenes", "keywords"],
      additionalProperties: false
    }
  }
}' > video-request.json

# 3) 非流式调用
curl --silent --show-error \
  "https://api.icodeeasy.cc/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: ${ICODEEASY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @video-request.json \
  --output video-response.json

# 4) 检查结束状态并提取业务 JSON
jq -e '.candidates[0].finishReason == "STOP"' video-response.json > /dev/null
jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | (.text // "")] | join("")' \
  video-response.json > video-result.json
jq -e . video-result.json

可以用下面的命令确认视频已被识别（promptTokensDetails 中会出现 VIDEO 模态的 token 数）：

jq '.usageMetadata' video-response.json

注意事项：

• 视频按输入 token 计费，与文本同价；usageMetadata 里 VIDEO 模态的 token 数就是计费依据。
• base64 会比原视频大约 1/3，建议单条视频控制在十几 MB 以内；更长的视频建议切分成多段分别发送。
• 不支持通过 fileData.fileUri 传外链：模型服务不会代拉外部 URL。请一律把视频下载到本地，按上面的 Demo 用 inlineData 发送。
• 视频请求耗时随片长增加，请把客户端超时适当调大（建议 5 分钟以上）；模型高峰期可能偶发 503 / “服务暂时不可用”，间隔几十秒重试即可。
• 本接口用于视频理解/分析，不包含视频生成。

常见问题