How to connect to Gemini 4 Neon API? APIYI native and OpenAI-compatible first request

How to connect to Gemini 4 Neon API? APIYI native and OpenAI-compatible first request

Author’s note: This article shows how to send your first request to Gemini 4 Neon over two different protocols on APIYI, and which fields and logs you should check once the request goes through.

Bottom line first: if your project already has an OpenAI Chat client, take the OpenAI-compatible Chat Completions endpoint — you only need to swap base_url and the model name. If you need to explicitly set Gemini’s thinking level, take Gemini’s native generateContent endpoint and specify it in generationConfig.thinkingConfig.thinkingLevel. Either way, get plain text working with the same short prompt first, then validate against the HTTP status, response body, stop reason, usage, and platform logs. Once that passes, move on to testing streaming output, tool calling, and the rest.

Here’s the background. Google shipped Gemini 4 Neon in the November 18, 2026 AI Studio changelog and declared it GA. APIYI confirmed it was listed at 11:45 Beijing time on 2026-11-20; the public pricing catalog shows gemini-4-neon, and the available groups are default and svip. Every example in this article is written against the APIYI docs and the SDK docs — no paid endpoints were called, and there are no measured statistics anywhere in this piece.

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


Gemini 4 Neon API Integration Knowledge Map and Index

The whole integration process comes down to three steps: pick the endpoint, send the request, then verify the output and logs. Each step’s output becomes the input for the next one. The table below puts the order of these three steps, the reasoning behind that order, and what you should walk away with at each stage — use it as a knowledge map or as a reading index.

No. Step What the previous step gives you Why it’s ordered this way Goal of this step
1 Choose the entry point (1.1 Chat-compatible / 1.2 Native and thinking levels) Your existing code stack and your need for thinking levels The entry point determines the URL, the auth style, and the field structure — everything downstream depends on it Commit to one protocol instead of debugging two paths at the same time
2 Send the same short request (2.1 native cURL / 2.2 Python SDK) The entry point and request format you’ve settled on A fixed, short prompt takes differences in model capability out of the picture and tests only whether the pipeline works Capture the full status code, response headers, and response body
3 Verify (3.1 fields / 3.2 identity and logs / 3.3 preserve evidence of failure) The raw response saved in step 2 Look at the response itself first, then line it up against platform logs — evidence from nearest to farthest Decide whether “text succeeded” actually holds up; if it doesn’t, leave evidence you can trace

Reading tip: If you only use one protocol, read the relevant subsection in Section 1, then jump straight to either 2.1 or 2.2 — but read Section 3 in full.

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

To Know: Essential Gemini 4 Neon API Terminology

Term Brief explanation
generateContent Gemini’s native non-streaming generation endpoint; the request body organizes content with contents and parts
thinkingLevel The thinking-level field under generationConfig.thinkingConfig in the native API; the examples in this article use high
thought part A part in a native response that’s flagged as thinking content; exclude it when concatenating the body text
finishReason / finish_reason The stop-reason fields for the native and compatible APIs, respectively
X-Shellapi-Request-Id The request identifier APIYI returns in the raw response headers or in the error message, used for troubleshooting

1 Choosing the Gemini 4 Neon API Entry Point

Both entry points target the same model; the difference lies in the protocol shape and which parameters you can control. Below is a side-by-side comparison, followed by two subsections explaining when to choose each.

Item OpenAI-compatible Chat Native Gemini
URL https://api.apiyi.com/v1 + Chat Completions https://api.apiyi.com/v1beta/models/gemini-4-neon:generateContent
Best for Projects that already have an OpenAI SDK or Chat client Projects that need explicit control over Gemini parameters
Thinking level Not passed in this article thinkingConfig.thinkingLevel
Answer text location choices[0].message.content the non-thought text inside candidates[0].content.parts
Model identifier model in the response modelVersion in the response (if returned)

1.1 Gemini 4 Neon Compatible Entry Point: Reuse Your Existing Chat Client

If your existing code uses the OpenAI Python SDK or another Chat Completions client, the lowest-effort change is to set base_url to https://api.apiyi.com/v1 and use gemini-4-neon as the model name; the message structure stays the same. The upside is that your business-layer code barely needs to change, and when something goes wrong it’s easier to tell whether the issue is the network, authentication, or the model.

There are a few boundaries to spell out if you take this route. First, don’t pass reasoning_effort. Google’s own compatibility layer maps it, but that doesn’t mean APIYI’s compatible endpoint makes the same promise. Second, this article doesn’t use the /v1/responses endpoint. Third, the older thinkingBudget syntax and the minimal level are also out of scope here. If you really need to control the thinking level, use the native entry point in section 1.2 instead.

1.2 Gemini 4 Neon Native Entry Point: Set the Thinking Level Explicitly

The native entry point uses Gemini’s own request structure. You pass the thinking level explicitly through generationConfig.thinkingConfig.thinkingLevel; the value used in the APIYI dedicated example is "high". Native responses also split thought content and answer text into different parts, so you need to filter explicitly when reading the answer; section 2.1 shows the exact approach.

For authentication, this native example uses the Authorization: Bearer header rather than the key query-parameter pattern commonly seen in Gemini’s official examples. When migrating existing native code, check this point first.


2 Send the Same Short Request to the Gemini 4 Neon API

Both protocols use the same prompt: Reply with exactly NEON_OK and nothing else. This prompt has a very short expected output, so the result is easy to judge. If the response isn’t NEON_OK, there’s a problem in the request path or parsing step, and you can rule out interference like “the model just has a different answer style.” Always read the API key from the APIYI_API_KEY environment variable—don’t write it into code or command history.

2.1 Gemini 4 Neon Native cURL and JSON Extraction

The command below saves the HTTP status code, response headers, and JSON response body separately. You’ll use all three in the Section 3 verification.

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

When reading the body, concatenate every text from candidates[0].content.parts that isn’t a thought—don’t just take the first part. The examples below use jq; if you don’t have jq installed, you can swap in any JSON parsing tool:

# Body: concatenate non-thought text
jq -r '[.candidates[0].content.parts[]? | select(.thought != true) | .text // empty] | join("")' neon_native_body.json

# Finish reason, usage, and model version (output null when a field is missing; don't fill in a value yourself)
jq '{finishReason: .candidates[0].finishReason, usageMetadata, modelVersion}' neon_native_body.json

# Platform request ID
grep -i "x-shellapi-request-id" neon_native_headers.txt

2.2 Calling Gemini 4 Neon with the Python OpenAI SDK and Reading the Response

The compatibility endpoint uses with_raw_response, so you get both the parsed object and the raw response headers. max_retries=0 disables automatic SDK retries so a single failure isn’t hidden by retries, and so you don’t end up with multiple logs on the platform that don’t match up to a specific request.

import os
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",  # APIYI OpenAI-compatible endpoint
    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)  # Before logging, confirm it doesn't contain sensitive information such as keys
except APIConnectionError as e:
    print("未拿到 HTTP 响应:", type(e).__name__)

One thing to watch in this code: when choices is empty, don’t write choices[0] directly, or you’ll throw an index error and hide the real problem. Connection errors have no HTTP status code and no response headers, so handle them separately from APIStatusError.


3 Validating the First Request to the Gemini 4 Neon API

The goal of validation is to determine whether “the plain-text request succeeded” actually holds. HTTP 2xx with the expected NEON_OK body only tells you that this one text request succeeded. It doesn’t prove model identity, and it shouldn’t be treated as a performance test result.

3.1 HTTP Status, Body, Stop Reason, and Usage

Check Native Field Compatibility Field Pass Condition
HTTP status stored status raw.status_code 2xx
Body concatenation of non-thought text choices[0].message.content equals NEON_OK
Stop reason candidates[0].finishReason choices[0].finish_reason recorded, and consistent with the body situation
Usage usageMetadata usage recorded, for cross-referencing against logs

If a field doesn’t exist in the response, record it as “not returned” rather than inferring a value from experience. Read the stop reason together with the body. When the body is empty and the stop reason isn’t a normal finish, the problem usually lies in the generation process, not in the parsing code.

3.2 What native modelVersion, compatible model, and logs can each tell you

Each of these pieces of information proves a different scope, so don’t treat them as interchangeable when you’re recording evidence:

Info Source Can tell you Cannot tell you
modelVersion Native response body (if returned) The model version the response reports about itself Can’t serve as identity proof on its own
model Compatible response body The model name the response reports about itself Same as above
Platform logs api.apiyi.com/log Cross-check this call by time, token, model, and usage The console doesn’t show the request ID
X-Shellapi-Request-Id Original response headers or error messages The request identifier used for platform troubleshooting It’s not responseId, not the Chat id, and not the SDK’s _request_id

When you’re cross-checking logs, match them using the time the request was sent, the token you used, the model name gemini-4-neon, and the usage figures. Since the console doesn’t display the request ID, you have to capture X-Shellapi-Request-Id yourself from the response headers — you won’t be able to look it up in the console after the fact.

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

3.3 How to Preserve Evidence When Gemini 4 Neon Returns No Body or the Request Fails

When a request fails or comes back with no body, don’t retry right away—save the evidence in this order:

  1. Save the HTTP status code. If it’s a connection error, note the exception type.
  2. Save the raw response headers and extract X-Shellapi-Request-Id from them.
  3. Save the raw response body or error message, and strip out sensitive content such as the API key.
  4. Record the stop reason and usage (if any), along with the time the request was sent, the token name used, and the model name.
  5. Go to api.apiyi.com/log, find the matching record by time and token, and then use the materials above to cross-check against the platform’s request ID troubleshooting docs.

One more thing to watch for with native responses: if the parts contain only thought content, the filtered body will end up empty. In that case, record “filtered body is empty” honestly—don’t treat thought content as body text just to get some output.


Once single-turn plain text passes acceptance the way described above, validate streaming output, tool calls, and other capabilities based on what your project needs. For each capability you add, run acceptance separately using the same method: “same request, save the raw response, cross-check logs.” This article doesn’t cover benchmarks or pricing—for that, refer to official announcements and the APIYI public catalog.

References

  1. Google AI Studio changelog (2026-11-18): aistudio.google.com/docs/changelog
  2. Gemini GenerateContentResponse structure: aistudio.google.com/api-reference/generate-content
  3. APIYI Gemini 4 Neon launch announcement and two-protocol examples: docs.apiyi.com/news/gemini-4-neon-launch.md
  4. APIYI Gemini response handling: docs.apiyi.com/api-capabilities/gemini/response-handling
  5. APIYI OpenAI-compatible response handling: docs.apiyi.com/api-capabilities/openai/response-handling
  6. APIYI request ID troubleshooting: docs.apiyi.com/faq/request-id-troubleshooting
  7. openai-python raw response access: github.com/openai/openai-python

A journey of a thousand miles begins with a single step. — Tao Te Ching

Similar Posts