Gemini 4 Neon API 怎麼接?API易原生與 OpenAI 兼容的首個請求

Gemini 4 Neon API 怎麼接?API易原生與 OpenAI 兼容的首個請求

作者注:本文說明在 API易用兩種協議向 Gemini 4 Neon 發出第一條請求,以及請求成功後應該覈對哪些字段和日誌。

結論先行:如果項目裏已經有 OpenAI Chat 客戶端,就走 OpenAI 兼容的 Chat Completions 入口,只需要換 base_url 和模型名。如果需要明確設置 Gemini 的思考檔位,就走 Gemini 原生 generateContent 入口,在 generationConfig.thinkingConfig.thinkingLevel 裏指定。無論選哪條路,都先用同一條短提示詞跑通純文本,再根據 HTTP 狀態、正文、停止原因、用量和平臺日誌做驗收。驗收通過以後,再去測流式輸出、工具調用等能力。

背景信息如下。Google 在 2026 年 11 月 18 日的 AI Studio 更新日誌中發佈了 Gemini 4 Neon,並宣佈 GA。API易於北京時間 2026-11-20 11:45 確認上架,公開價格目錄裏可以看到 gemini-4-neon,可用分組爲 default 和 svip。本文的示例都是按 API易文檔和 SDK 文檔編寫的,沒有調用收費接口,文中也沒有任何實測統計。

gemini-4-neon-api-first-request-native-openai-compatible-zh-hant-image-0


Gemini 4 Neon API 接入知識地圖與索引

整個接入過程分三步:選接口、發請求、覈對輸出與日誌。每一步的產出都是下一步的輸入。下表把這三步的先後關係、安排理由和每一步要達到的目標放在一起,可以當作知識地圖,也可以當作閱讀索引。

編號 步驟 前一步提供什麼 爲什麼這樣排 本步目標
1 選入口(1.1 兼容 Chat / 1.2 原生與思考檔) 你現有的代碼棧和對思考檔位的需求 入口決定 URL、鑑權寫法和字段結構,後面所有步驟都取決於它 確定一條協議,不在兩條路上同時排錯
2 發同一條短請求(2.1 原生 cURL / 2.2 Python SDK) 已確定的入口和請求格式 用固定的短提示詞,可以把模型能力的差異排除在外,只檢驗鏈路是否通 拿到完整的狀態碼、響應頭和響應體
3 驗收(3.1 字段 / 3.2 身份與日誌 / 3.3 失敗留證) 第 2 步保存的原始響應 先看響應本身,再去和平臺日誌對照,證據從近到遠 判斷“文本成功”是否成立;如果不成立,留下可追查的證據

閱讀建議:只用其中一種協議的讀者,第 1 節讀完對應小節以後,直接看 2.1 或 2.2 中的一個,第 3 節需要完整讀。

gemini-4-neon-api-first-request-native-openai-compatible-zh-hant-image-1

To Know:Gemini 4 Neon API 必要術語

術語 簡明解釋
generateContent Gemini 原生的非流式生成接口,請求體裏用 contents 和 parts 組織內容
thinkingLevel 原生接口 generationConfig.thinkingConfig 下的思考檔位字段,本文示例取 high
thought part 原生響應中被標記爲思考內容的 part,拼接正文時要排除
finishReason / finish_reason 原生和兼容接口各自的停止原因字段
X-Shellapi-Request-Id API易在原始響應頭或錯誤信息裏返回的請求標識,用於排障

1 選擇 Gemini 4 Neon API 接入入口

兩個入口指向同一個模型,區別在於協議形態和可以控制的參數。下面先給出對照,再分兩小節說明選擇理由。

對比項 OpenAI 兼容 Chat Gemini 原生
地址 https://api.apiyi.com/v1 + Chat Completions https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent
適合誰 已有 OpenAI SDK 或 Chat 客戶端的項目 需要顯式控制 Gemini 參數的項目
思考檔位 本文不傳相關參數 thinkingConfig.thinkingLevel
正文位置 choices[0].message.content candidates[0].content.parts 中非 thought 的 text
模型標識 響應裏的 model 響應裏的 modelVersion(如果返回)

1.1 Gemini 4 Neon 兼容入口:沿用現有 Chat 客戶端

已有代碼基於 OpenAI Python SDK 或其他 Chat Completions 客戶端時,改動最少的做法是把 base_url 換成 https://api.apiyi.com/v1,模型名寫 gemini-4-neon,消息結構不用動。這樣做的好處是業務層代碼幾乎不用改,出問題時也比較容易判斷問題在網絡、鑑權還是模型。

使用這條路有幾條邊界需要說清楚。第一,不要傳 reasoning_effort。Google 自己的兼容層對它有映射,但這不代表 API易的兼容入口也做了同樣的承諾。第二,本文不使用 /v1/responses 接口。第三,舊的 thinkingBudget 寫法和 minimal 檔位也不在本文範圍內。如果你確實需要控制思考檔位,請改走 1.2 的原生入口。

1.2 Gemini 4 Neon 原生入口:明確設置思考檔位

原生入口使用 Gemini 自己的請求結構。思考檔位通過 generationConfig.thinkingConfig.thinkingLevel 顯式傳入,API易專項用例裏用的值是 "high"。原生響應還會把思考內容和正文分成不同的 part,所以讀取正文時要主動過濾,2.1 節給出具體寫法。

鑑權方面,這個原生用例用的是 Authorization: Bearer 請求頭,沒有使用 Gemini 官方常見的 key 參數寫法。遷移已有的原生代碼時,要先覈對這一處。


2 向 Gemini 4 Neon API 發送同一條短請求

兩種協議使用同一條提示詞:Reply with exactly NEON_OK and nothing else. 這條提示詞的預期輸出很短,結果也容易判斷。只要返回不是 NEON_OK,就說明鏈路或解析環節有問題,可以排除“模型回答風格不同”這類干擾。API Key 一律從環境變量 APIYI_API_KEY 讀取,不要寫進代碼或命令歷史。

2.1 Gemini 4 Neon 原生 cURL 與 JSON 取值

下面的命令會把 HTTP 狀態碼、響應頭和 JSON 響應體分別保存下來,第 3 節驗收時會用到全部三項。

curl -sS -X POST "https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent" \
  -H "Authorization: Bearer ${APIYI_API_KEY}" \
  -H "Content-Type: application/json" \
  -D neon_native_headers.txt \
  -o neon_native_body.json \
  -w "%{http_code}\n" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Reply with exactly NEON_OK and nothing else."}]}
    ],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }' > neon_native_status.txt

讀取正文時,要把 candidates[0].content.parts 中所有不是 thought 的 text 拼接起來,不能只取第一個 part。以下示例用 jq 處理,沒有安裝 jq 的話,可以換成任何 JSON 解析工具:

# 正文:拼接非 thought 的 text
jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | .text // empty] | join("")' neon_native_body.json

# 停止原因、用量、模型版本(字段不存在時輸出 null,不要自行補值)
jq '{finishReason: .candidates[0].finishReason, usageMetadata, modelVersion}' neon_native_body.json

# 平臺請求標識
grep -i "x-shellapi-request-id" neon_native_headers.txt

2.2 Gemini 4 Neon 的 Python OpenAI SDK 調用與返回讀取

兼容入口使用 with_raw_response,這樣既能拿到解析後的對象,也能讀到原始響應頭。max_retries=0 用來關閉 SDK 的自動重試,避免一次失敗被重試掩蓋,同時防止平臺上出現多條日誌,對不上是哪一次請求。

import os
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",  # API易 OpenAI 兼容入口
    max_retries=0,
    timeout=120.0,
)

try:
    raw = client.chat.completions.with_raw_response.create(
        model="gemini-4-neon",
        messages=[{"role": "user", "content": "Reply with exactly NEON_OK and nothing else."}],
        max_tokens=4096,
    )
    print("HTTP:", raw.status_code)
    print("X-Shellapi-Request-Id:", raw.headers.get("x-shellapi-request-id"))

    completion = raw.parse()
    if not completion.choices:
        print("choices 爲空,不讀取正文")
    else:
        choice = completion.choices[0]
        print("content:", choice.message.content)
        print("finish_reason:", choice.finish_reason)
    print("usage:", completion.usage)
    print("model:", completion.model)

except APIStatusError as e:
    print("HTTP:", e.status_code)
    print("X-Shellapi-Request-Id:", e.response.headers.get("x-shellapi-request-id"))
    print("error:", e.message)  # 記錄前確認不含密鑰等敏感信息
except APIConnectionError as e:
    print("未拿到 HTTP 響應:", type(e).__name__)

這段代碼有一處需要特別注意:choices 爲空時,不要直接寫 choices[0],否則會拋出索引錯誤,把真正的問題掩蓋掉。連接錯誤沒有 HTTP 狀態碼,也沒有響應頭,所以要和 APIStatusError 分開處理。


3 驗收 Gemini 4 Neon API 的首個請求

驗收的目標是判斷“純文本請求成功”這件事是否成立。HTTP 2xx 並且正文是預期的 NEON_OK,只能說明這一次文本請求成功了。它不能證明模型身份,也不能當作性能測試結果。

3.1 HTTP 狀態、正文、停止原因和用量

檢查項 原生字段 兼容字段 通過條件
HTTP 狀態 保存的 status raw.status_code 2xx
正文 非 thought text 拼接 choices[0].message.content 等於 NEON_OK
停止原因 candidates[0].finishReason choices[0].finish_reason 已記錄,並與正文情況一致
用量 usageMetadata usage 已記錄,用於和日誌對照

如果某個字段在響應裏不存在,就把它記爲“未返回”,不要按經驗去推斷它的值。停止原因要和正文放在一起看。正文爲空,而停止原因又不是正常結束時,問題通常出在生成過程,而不是解析代碼。

3.2 原生 modelVersion、兼容 model 與日誌各能說明什麼

這幾項信息各自能證明的範圍不同,記錄時不要互相替代:

信息 來源 能說明 不能說明
modelVersion 原生響應體(如果返回) 響應自報的模型版本 不能單獨作爲身份證明
model 兼容響應體 響應自報的模型名 同上
平臺日誌 api.apiyi.com/log 按時間、令牌、模型、用量覈對這次調用 控制檯不顯示請求 ID
X-Shellapi-Request-Id 原始響應頭或錯誤信息 平臺排障時用的請求標識 它不是 responseId、Chat id,也不是 SDK 的 _request_id

覈對日誌時,用請求發出的時間、所用令牌、模型名 gemini-4-neon 以及用量數字去匹配。由於控制檯不顯示請求 ID,X-Shellapi-Request-Id 必須自己從響應頭裏保存下來,事後在控制檯是查不到的。

gemini-4-neon-api-first-request-native-openai-compatible-zh-hant-image-2

3.3 Gemini 4 Neon 沒有正文或請求失敗時怎樣留證

請求失敗或者沒有正文時,先不要重試,按下面的順序保存證據:

  1. 保存 HTTP 狀態碼。如果是連接錯誤,記下異常類型。
  2. 保存原始響應頭,從中取出 X-Shellapi-Request-Id。
  3. 保存原始響應體或錯誤信息,並去掉 API Key 等敏感內容。
  4. 記錄停止原因和用量(如果有),以及請求發出的時間、所用令牌名稱、模型名。
  5. 到 api.apiyi.com/log 按時間和令牌找到對應的記錄,再拿着上面的材料對照平臺的請求 ID 排障文檔處理。

關於原生響應還有一點要注意。如果 parts 裏只有 thought 內容,過濾後的正文就會是空的。這時應該如實記錄“過濾後正文爲空”,不要爲了拿到輸出而把 thought 內容當成正文。


單輪純文本按上面的方式驗收通過以後,再根據項目需要去驗證流式輸出、工具調用等能力。每加一項能力,都按“同一請求、保存原始響應、對照日誌”的方法單獨驗收。本文不涉及跑分和價格,相關信息請以官方發佈和 API易公開目錄爲準。

參考資料

  1. Google AI Studio 更新日誌(2026-11-18): aistudio.google.com/docs/changelog
  2. Gemini GenerateContentResponse 結構: aistudio.google.com/api-reference/generate-content
  3. API易 Gemini 4 Neon 上架公告與兩協議示例: docs.apiyi.com/news/gemini-4-neon-launch.md
  4. API易 Gemini 響應處理: docs.apiyi.com/api-capabilities/gemini/response-handling
  5. API易 OpenAI 兼容響應處理: docs.apiyi.com/api-capabilities/openai/response-handling
  6. API易 請求 ID 排障: docs.apiyi.com/faq/request-id-troubleshooting
  7. openai-python 原始響應訪問: github.com/openai/openai-python

千里之行,始於足下。——《道德經》

Similar Posts