← 返回 Blog
UseAIAPIAI API3min

Gemini 3.1 Pro API 国内直连实战：base_url 怎么改、model 名填什么、thinking_level 怎么设——一份不废话的迁移清单

将代码从境外服务器迁移到国内环境调用大模型 API，本身并非技术难题。真正容易踩坑的只有三个核心参数：base_url、模型名、thinking_level。稍有不慎，就会出现 403、404 错误，甚至导致账单翻倍。

GeminiGemini 3.1 ProGemini 3.1 Pro API 国内迁移

Gemini 3.1 Pro API 国内迁移实战指南：三大核心参数避坑 半小时完成切换

将代码从境外服务器迁移到国内环境调用大模型 API，本身并非技术难题。真正容易踩坑的只有三个核心参数：base_url、模型名、thinking_level。稍有不慎，就会出现 403、404 错误，甚至导致账单翻倍。

本文不讲背景知识，不带主观情绪，只提供可直接落地的实用信息。按照步骤操作，半小时内即可将代码中的官方 SDK 切换为国内直连模式。

一、base_url 配置：v1 还是 v1beta？填错直接返回 404

不同大模型厂商的 API 路径规范各不相同：OpenAI 使用 /v1 路径，Anthropic Claude 使用根域名，Google Gemini 则使用 /v1beta 路径。路径填写错误是导致 API 调用失败的第一大原因。

方案一：OpenAI 兼容 SDK 接入（国内首选方案）

这是目前国内开发者最省力的接入方式。专业的 API 服务平台会将 Gemini 的私有 API 协议封装成标准的 OpenAI 接口格式。开发者无需更换 SDK，只需修改两行配置即可完成切换：

python

运行

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",        # 从API服务平台获取
    base_url="https://你的API服务地址/v1"   # API服务平台提供的国内中转地址
)

所有国内正规 API 服务平台的 base_url 路径统一以 /v1 结尾，因为平台会自动将 Gemini 的私有协议翻译成 OpenAI 兼容格式，大幅降低开发者的适配成本。

方案二：Google 官方 SDK 直连（适合境外服务器或自建代理）

如果通过官方通道调用，base_url 需要填写根域名，并单独指定 api_version 参数：

python

运行

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_GOOGLE_API_KEY",
    http_options={
        "base_url": "https://generativelanguage.googleapis.com",
        "api_version": "v1beta"
    }
)

SDK 会自动拼接完整的请求路径：/v1beta/models/{model}:generateContent。

自建反代专用配置

如果使用 Cloudflare Workers 自建反向代理，直接在 base_url 中填写自己的代理域名即可。建议绑定自定义域名，默认的 *.workers.dev 域名在国内部分地区访问不稳定。

二、模型名配置：使用官方标识符 切勿自行编造

无论采用哪种接入方式，都必须直接复制官方提供的模型标识符，切勿自行修改或编造字符串。

✅ 官方标准模型标识符：gemini-3.1-pro-preview

OpenAI 兼容格式调用示例：

python

运行

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",  # 必须使用官方标识符
    messages=[{"role": "user", "content": "Hello"}]
)

⚠️ 重要时间节点提醒：自 2026 年 3 月 6 日起，Google API 中的所有别名已全部切换为指向 Gemini 3.1 Pro Preview，旧版模型已于 3 月 9 日正式停用。如果仍在使用gemini-3-pro-preview，极大概率会返回 404 或 "model not found" 错误。

调用多模态功能时也使用相同的标识符。Gemini 3.1 Pro 原生支持文本、图像、音频、视频同步处理，无需为不同模态切换模型名。

三、thinking_level 配置：成本差异巨大 按需选择最关键

这是 Gemini 3.1 Pro 最容易被忽略，但对性价比影响最大的参数。

模型在处理请求时，会先进行内部推理，这部分内容不会展示给用户，但同样会计费。一个仅 13 个 token 的问题，可能生成近 900 个输出 token，其中超过 95% 是不可见的推理 token。

表格

推理档位功能说明成本对比
low快速响应模式，推理 token 预算最低相比 high 档，简单任务可节省 60%～80% 的推理成本
medium平衡推理模式（3.1 Pro 新增核心档）成本仅约为 Gemini 3 Pro high 档的 40%
high深度推理模式（默认），激活 Deep Think Mini 能力同等推理深度下，比上一代 high 档节省约 30% 成本

在 Vercel AI SDK 中配置示例：

javascript

运行

const result = streamText({
  model: "google/gemini-3.1-pro-preview",
  prompt: "Your prompt here",
  providerOptions: {
    google: {
      thinking_level: "medium"   // 可选值：low | medium | high
    }
  }
})

使用 LiteLLM 聚合层时，它可以自动将 OpenAI 的reasoning_effort参数映射到 Gemini 的thinkingLevel，支持使用 mini/low/medium/high 进行设置。

迁移参数建议：

  • 如果之前使用 Gemini 3 Pro 的 high 档，切换到 3.1 Pro 后建议先使用 medium 档，输出质量相近但成本大幅降低
  • 仅在处理复杂代码调试、系统架构设计等需要深度推理的任务时再切换到 high 档
  • 日常问答、简单翻译等场景直接使用 low 档，比 high 档节省 80% 以上的 token 成本

四、完整可运行示例（国内中转 + OpenAI 兼容 SDK）

python

运行

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://你的API服务地址/v1"  # 替换为实际的API服务地址
)

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {"role": "system", "content": "You are a code reviewer."},
        {"role": "user", "content": "Review the memory leak risk of this code"}
    ],
    temperature=0.3,
    max_tokens=2048,
    extra_body={
        "thinking": {               # 对应thinking_level参数
            "type": "enabled",
            "budget_tokens": 8192   # medium档对应约8192个推理token
        }
    }
)

print(response.choices[0].message.content)

总结

Gemini 3.1 Pro API 国内迁移的核心原则只有三条：

  • base_url 必须与接入方式对应的路径格式保持一致
  • 模型名严格使用官方提供的标准标识符
  • thinking_level 根据任务复杂度设置到合适档位

遇到调用失败的情况，99% 的问题都出在这三个参数上。

在 AI 技术快速迭代的今天，企业和开发者面临的最大挑战，不再是找不到强大的模型，而是如何便捷、经济地接入各类主流大模型，并根据不同的业务场景灵活选择最适合的工具。UseAIAPI 提供全球热门 AI 大模型一站式接入服务，全面覆盖 Gemini、Claude、ChatGPT、DeepSeek 等最新版本的 AI 大模型，无需分别对接多个平台，大幅降低集成成本和维护难度。同时，平台还提供专业的企业级定制化服务，能够根据企业的具体业务需求，量身打造专属的 AI 解决方案，帮助企业快速搭建高效稳定的 AI 开发体系。在成本方面，UseAIAPI 推出了极具竞争力的价格政策，优惠折扣最低可达官方价格的 50%，能够有效帮助企业控制高强度 AI 应用场景下的算力消耗成本，让 AI 技术真正成为推动业务增长的核心动力。