TL;DR
Gemini 4 Hydrogen API jest dostępne przez Gemini API Google oraz wspierane bramki firm trzecich, takie jak CometAPI. Najpierw wybierz trasę: użyj Google, jeśli potrzebujesz funkcji specyficznych dla dostawcy i kontroli konta, albo CometAPI, jeśli chcesz zunifikowaną bramkę modeli lub klienta zgodnego z OpenAI. Zacznij od małego żądania tekstowego, a potem dodaj strumieniowanie, historię rozmowy, pliki i narzędzia.
Potrzebujesz Python 3.10 lub nowszego, klucza dla wybranej trasy oraz dostępu do gemini-4-hydrogen. Opcjonalny przykład w JavaScript wymaga Node.js 22 lub nowszego. Przez cały samouczek przechowuj dane uwierzytelniające w środowisku serwera.
Najważniejsze wnioski
- Używaj
gemini-4-hydrogenjako identyfikatora modelu dla Gemini 4 Hydrogen API. - Google i CometAPI mają oddzielne dane logowania i rozliczenia. Dopasuj klucz do wybranego endpointu.
- Zacznij od natywnego GenerateContent; użyj interfejsu zgodnego z OpenAI w CometAPI, gdy pasuje do istniejącego klienta czatu.
- Zachowuj pełną odpowiedź modelu w historii wieloturnowej, łącznie z podpisami, zanim zwrócisz odpowiedź uzupełniającą lub wynik narzędzia.
- Porównuj faktyczne zużycie tokenów i ukończone zadania przy wyborze trasy; standardowy przykład cen tokenów znajduje się w sekcji cennika.
Czym jest Gemini 4 Hydrogen API?
Google wprowadziło Hydrogen 12 listopada 2026 r. API przyjmuje prompty i obsługiwane pliki, a następnie zwraca wygenerowany tekst lub ustrukturyzowane wywołania funkcji do obsłużenia przez Twoją aplikację. Nie musisz samodzielnie hostować modelu.
Zacznij od żądania wyłącznie tekstowego i zweryfikuj zwrócony tekst, powód zakończenia oraz zużycie tokenów, zanim dodasz narzędzia lub pliki. Gdy to zadziała, dodaj stan rozmowy lub narzędzie firmowe tylko do odczytu, zamiast budować cały przepływ pracy naraz.
Specyfikacje Gemini 4 Hydrogen API
| Specyfikacja | Udokumentowana przez Google zdolność modelu |
|---|---|
| Model ID | gemini-4-hydrogen |
| Wejście | Tekst, obrazy, audio, wideo i obsługiwane dokumenty |
| Wyjście | Tekst, z ustrukturyzowanymi częściami wywołań funkcji przy narzędziach |
| Ujednolicony budżet kontekstu | 1 048 576 tokenów łącznie dla wejścia i wyjścia |
| Pojedynczy segment wyjścia | Do 65 536 tokenów, w tym rozumowanie i wywołania funkcji |
| Funkcje aplikacji | Kontrola poziomu rozumowania, ustrukturyzowane wyjście i wywoływanie funkcji |
To są możliwości modelu, a nie gwarancja, że każda bramka udostępnia wszystkie funkcje dostawcy. Poniższe przykłady używają standardowych pól żądania i krótkich generacji pierwszoplanowych.
Oficjalne API Google vs CometAPI
Obie trasy obsługują żądania Gemini, ale korzystają z różnych endpointów, danych logowania i systemów rozliczeń. Używaj Google dla funkcji specyficznych dla dostawcy; używaj CometAPI dla zunifikowanej bramki lub istniejącego klienta zgodnego z OpenAI.
| Decyzja | Google Gemini Developer API | Integracja Gemini w CometAPI |
|---|---|---|
| Natywny host API | generativelanguage.googleapis.com | api.cometapi.com |
| Klucz API w tym poradniku | GEMINI_API_KEY | COMETAPI_KEY |
| Konto i rozliczenia | Zarządzane przez Google | Zarządzane przez CometAPI |
| Najlepszy punkt startu | Funkcje specyficzne dla Google i kontrola konta | Zunifikowany dostęp do modeli lub istniejący klient zgodny z OpenAI |
Zachowaj ten sam prompt i budżet wyjścia przy porównywaniu dwóch tras, aby wyniki były miarodajne. Alternatywy w JavaScript i zgodne z OpenAI pozostają jawnie skonfigurowane dla CometAPI.
Jak korzystać z Gemini 4 Hydrogen API krok po kroku?
Krok 1: Utwórz klucz API
Dla CometAPI utwórz konto i wygeneruj klucz w konsoli tokenów API. Dla bezpośredniego dostępu Google utwórz klucz Gemini API w Google AI Studio. Potwierdź dostęp do modelu i rozliczenia lub dostępne limity dla wybranego konta.
Przechowuj klucz bezpiecznie. Klucz CometAPI nie uwierzytelni żądania do endpointu Google, a klucz Google nie uwierzytelni żądania do CometAPI.
Ustaw klucz dla wybranej trasy w Bash; potrzebujesz tylko jednego z tych przypisań.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Ustaw odpowiedni klucz w PowerShell w systemie Windows.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
Krok 2: Wyślij pierwsze żądanie za pomocą cURL
Wyślij natywne żądanie tekstowe przez CometAPI z terminala Bash.
curl "https://api.cometapi.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Alternatywnie, wyślij to samo natywne żądanie bezpośrednio do Google z kluczem Google API.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Po pomyślnym żądaniu zweryfikuj trzy pola: candidates[0].content.parts dla widocznego tekstu, finishReason dla statusu zakończenia i usageMetadata dla zużycia tokenów. Napraw błędy uwierzytelnienia lub żądania przed dodaniem dalszego kodu aplikacji.
Krok 3: Skonfiguruj klienta w Pythonie i wyślij żądanie
Zainstaluj pakiety używane w przykładach Pythona.
python -m pip install requests openai
Zapisz ten pomocniczy plik jako hydrogen_client.py. Pozostaw PROVIDER ustawiony na cometapi dla CometAPI albo ustaw na google dla bezpośredniego dostępu do Gemini Developer API. Późniejsze przykłady natywne importują ten plik, więc zachowują wybraną trasę.
Skonfiguruj wybrany endpoint i zdefiniuj wielokrotnego użytku pomocnicze funkcje żądania i ekstrakcji tekstu.
import os
import requests
MODEL = "gemini-4-hydrogen"
PROVIDER = "cometapi" # Change to "google" for direct access.
ROUTES = {
"cometapi": ("https://api.cometapi.com", "COMETAPI_KEY"),
"google": ("https://generativelanguage.googleapis.com", "GEMINI_API_KEY"),
}
BASE_URL, KEY_NAME = ROUTES[PROVIDER]
API_KEY = os.environ[KEY_NAME]
URL = f"{BASE_URL}/v1beta/models/{MODEL}:generateContent"
def generate(payload):
response = requests.post(
URL,
headers={"x-goog-api-key": API_KEY},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
def visible_text(data):
candidates = data.get("candidates") or []
if not candidates:
raise ValueError("No candidate returned; inspect promptFeedback.")
candidate = candidates[0]
parts = candidate.get("content", {}).get("parts", [])
text = "".join(
part.get("text", "") for part in parts
if not part.get("thought", False)
)
if not text:
raise ValueError(
f"No visible text; inspect parts and finishReason: "
f"{candidate.get('finishReason')}"
)
return text
Zapisz poniższe jako hydrogen.py obok pliku pomocniczego. Wypisuje odpowiedź, powód zakończenia i zużycie, abyś mógł odróżnić kompletną odpowiedź od wyjścia zatrzymanego na limicie tokenów.
Wyślij żądanie tekstowe przy użyciu skonfigurowanego dostawcy.
from hydrogen_client import generate, visible_text
data = generate({
"contents": [{"role": "user", "parts": [{
"text": "Explain API rate limiting in three sentences."
}]}],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
},
})
print(visible_text(data))
candidate = data["candidates"][0]
print("Finish reason:", candidate.get("finishReason"))
print("Usage:", data.get("usageMetadata", {}))
Uruchom skrypt w terminalu, w którym ustawiłeś wybrany klucz API.
python hydrogen.py
Przeczytaj odpowiedź, a następnie sprawdź finishReason, aby zobaczyć, dlaczego generacja się zatrzymała. W usageMetadata sprawdź, ile tokenów zużyło żądanie. MAX_TOKENS oznacza, że odpowiedź może być niekompletna, nawet jeśli żądanie HTTP się powiodło.
Użyj JavaScript lub klienta zgodnego z OpenAI
Wybierz przykład pasujący do Twojej aplikacji. Przykład dla Node.js wysyła natywne żądanie Gemini. Jeśli już używasz SDK OpenAI, przejdź do przykładu w Pythonie poniżej.
JavaScript z Node.js
Zapisz poniższe jako hydrogen.js i uruchom node hydrogen.js. Wysyła ten sam kształt natywnego żądania i wyodrębnia wszystkie widoczne części tekstowe.
Wyślij natywne żądanie GenerateContent z Node.js.
const apiKey = process.env.COMETAPI_KEY;
if (!apiKey) throw new Error("Set COMETAPI_KEY before running this script.");
const baseUrl = "https://api.cometapi.com";
const model = "gemini-4-hydrogen";
async function main() {
const response = await fetch(
`${baseUrl}/v1beta/models/${model}:generateContent`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-goog-api-key": apiKey
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [
{
text: "Explain how an AI coding agent works."
}
]
}
],
generationConfig: {
maxOutputTokens: 4096,
thinkingConfig: {
thinkingLevel: "MEDIUM"
}
}
})
}
);
if (!response.ok) {
throw new Error(
`API error: ${response.status} ${await response.text()}`
);
}
const data = await response.json();
const candidate = data.candidates?.[0];
const text = (candidate?.content?.parts || [])
.filter(part => !part.thought)
.map(part => part.text || "")
.join("");
if (!text) {
throw new Error(`No visible text; finishReason=${candidate?.finishReason}`);
}
console.log(text);
}
main().catch(console.error);
Python z SDK OpenAI
Jeśli Twoja aplikacja już używa SDK OpenAI, CometAPI również udostępnia POST /v1/chat/completions. Najprostsza migracja to zmiana klucza API, bazowego URL i identyfikatora modelu. Użyj tej trasy dla typowych przepływów czatowych; użyj natywnego endpointu Gemini, gdy potrzebujesz pól specyficznych dla Gemini.
Utwórz żądanie Chat Completions przez CometAPI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
response = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": "Explain how an AI coding agent works."
}
]
)
print(response.choices[0].message.content)
Przykłady natywne używają contents i generationConfig; Chat Completions używa messages i własnych pól żądania. Zachowuj każde żądanie w jednym formacie zamiast kopiować pola natywne do wywołania SDK, które ich nie przyjmuje.
Zaawansowane funkcje Gemini 4 Hydrogen API
Poniższe przykłady ponownie używają hydrogen_client.py z sekcji konfiguracji, więc działają z dostawcą wybranym w PROVIDER. Przykład strumieniowania poniżej używa oddzielnego klienta CometAPI Chat Completions, co pasuje do istniejącej aplikacji zgodnej z OpenAI.
Skonfiguruj rozumowanie i ustrukturyzowane wyjście
Użyj generationConfig, aby ustawić thinkingConfig.thinkingLevel na LOW, MEDIUM, HIGH lub XHIGH. Wybierz budżet wyjścia, który pozostawia miejsce zarówno na rozumowanie, jak i widoczną odpowiedź. Gdy aplikacja oczekuje JSON, użyj responseMimeType i responseSchema zamiast polegać wyłącznie na prośbie o formatowanie w języku naturalnym.
Ustaw budżet wyjścia i poziom rozumowania dla natywnego żądania.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Strumieniuj odpowiedzi przez CometAPI
Strumieniowanie zwraca generowaną treść stopniowo zamiast czekać na pełną odpowiedź. Jest to przydatne dla interfejsów czatowych, asystentów kodowania i aplikacji, w których liczy się postrzegana latencja.
CometAPI dokumentuje strumieniowanie Chat Completions z stream=true. Przykład w Pythonie obsługuje fragmenty bez choices, które mogą wystąpić w odpowiedziach strumieniowych.
Wypisuj tekst w miarę napływu przez endpoint zgodny z OpenAI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
stream = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": (
"Write a Python function that validates an email "
"address and explain the main checks."
)
}
],
stream=True
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta;
if delta and delta.content:
print(delta.content, end="", flush=True)
print()
Dla klienta natywnego CometAPI dokumentuje streamGenerateContent z Server-Sent Events. Ta trasa zwraca obiekty odpowiedzi GenerateContent zamiast delt Chat Completions. Dopasuj parser do trasy; zachowanie strumieniowania może się różnić między natywnym endpointem Gemini a bramką zgodną z OpenAI. Przetestuj dokładną trasę Hydrogen używaną przez Twoją aplikację przed migracją istniejącego klienta strumieniowego.
Zachowaj historię rozmowy wieloturnowej
Wyślij poprzednie tury użytkownika i modelu z kolejnym żądaniem. Zachowaj kompletny obiekt treści modelu zamiast odtwarzać go z widocznego tekstu; pozwala to zachować zwrócone metadane na następną turę. Zapisz przykład jako hydrogen_history.py obok współdzielonego pliku pomocniczego.
Wykonaj dwa powiązane żądania, zachowując pełną pierwszą odpowiedź modelu.
from hydrogen_client import generate, visible_text
history = [{"role": "user", "parts": [{
"text": "Suggest a simple queue-based background job architecture."
}]}]
config = {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
}
first = generate({"contents": history, "generationConfig": config})
print(visible_text(first))
candidate = first["candidates"][0]
if candidate.get("finishReason") != "STOP":
raise RuntimeError("The first turn did not finish normally.")
history.append(candidate["content"])
history.append({"role": "user", "parts": [{
"text": "Now identify three failure scenarios in that design."
}]})
second = generate({"contents": history, "generationConfig": config})
print(visible_text(second))
print("Finish reason:", second["candidates"][0].get("finishReason"))
Uruchom python hydrogen_history.py. Druga odpowiedź powinna odnosić się do projektu z pierwszej tury. W tym przykładzie pozostaw wcześniejszy prefiks rozmowy bez zmian; długotrwałe aplikacje potrzebują osobnej polityki kompresji i limitów kontekstu.
Wyślij obrazy i pliki PDF
Hydrogen obsługuje rozumienie obrazów i dokumentów. W natywnym formacie żądania Gemini dodaj część inlineData obok instrukcji tekstowej. Jest to przydatne do analizy zrzutów ekranu, diagramów architektury, zeskanowanych formularzy i ekstrakcji raportów.
Zapisz ten przykład jako analyze_file.py obok hydrogen_client.py. Wysyła jeden lokalny obraz lub PDF, więc możesz użyć tego samego kodu dla obu typów wejścia. Użyj małego pliku dla pierwszego żądania; Base64 zwiększa rozmiar żądania.
Analizuj lokalny plik PNG, JPEG lub PDF, używając współdzielonego klienta natywnego.
import base64
import sys
from pathlib import Path
from hydrogen_client import generate, visible_text
path = Path(sys.argv[1])
mime_types = {
".png": "image/png", ".jpg": "image/jpeg",
".jpeg": "image/jpeg", ".pdf": "application/pdf",
}
mime_type = mime_types.get(path.suffix.lower())
if mime_type is None:
raise ValueError("Choose a PNG, JPEG, or PDF file.")
data = generate({
"contents": [{"role": "user", "parts": [
{"text": "Summarize this file and identify the key findings."},
{"inlineData": {
"mimeType": mime_type,
"data": base64.b64encode(path.read_bytes()).decode("ascii"),
}},
]}],
"generationConfig": {"maxOutputTokens": 4096},
})
print(visible_text(data))
Uruchom przykład z plikiem, używając własnego dokumentu lub obrazu.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
Bajty pliku muszą odpowiadać zadeklarowanemu typowi MIME. Zmieniona nazwa rozszerzenia nie konwertuje pliku. Jeśli przesyłanie zostało odrzucone, sprawdź błąd pod kątem limitu rozmiaru lub formatu przed ponowną próbą; nie zakładaj, że adres URI pliku hostowanego przez Google jest dostępny przez bramkę firmy trzeciej.
Podłącz narzędzia kontrolowane przez aplikację
Wywoływanie funkcji pozwala modelowi poprosić o operację, którą wykonuje Twoja aplikacja. Model zwraca ustrukturyzowane wywołanie funkcji; Twoja aplikacja weryfikuje argumenty, wykonuje funkcję i odsyła wynik.
Ten przykład używa małej, fikcyjnej bazy zamówień. Zapisz go jako order_agent.py obok współdzielonego klienta. Implementuje pełną rundę, ogranicza pętlę do czterech żądań i zachowuje pełną treść modelu — w tym zwrócone podpisy — między turami.
Uruchom ograniczoną pętlę wywołań funkcji na lokalnej demonstracyjnej bazie danych.
from hydrogen_client import generate, visible_text
orders = {"DEMO-1001": {"status": "shipped", "carrier": "Example Carrier"}}
tools = [{"functionDeclarations": [{
"name": "lookup_order",
"description": "Retrieve a demonstration order by its order ID.",
"parameters": {
"type": "OBJECT",
"properties": {"order_id": {"type": "STRING"}},
"required": ["order_id"],
},
}]}]
history = [{"role": "user", "parts": [{
"text": "Use lookup_order to check the status of DEMO-1001."
}]}]
for _ in range(4):
data = generate({
"contents": history,
"tools": tools,
"generationConfig": {"maxOutputTokens": 4096},
})
candidates = data.get("candidates") or []
if not candidates or not candidates[0].get("content"):
raise RuntimeError("No model content returned.")
model_content = candidates[0]["content"]
calls = [
part["functionCall"] for part in model_content.get("parts", [])
if "functionCall" in part
]
if not calls:
print(visible_text(data))
break
history.append(model_content) # Preserve all parts and signatures.
results = []
for call in calls:
args = call.get("args", {})
order_id = args.get("order_id") if isinstance(args, dict) else None
if call.get("name") != "lookup_order":
raise ValueError("Unexpected function name.")
if not isinstance(order_id, str) or not order_id:
raise ValueError("order_id must be a non-empty string.")
result = orders.get(order_id, {"error": "Order not found"})
reply = {"name": call["name"], "response": result}
if "id" in call:
reply["id"] = call["id"]
results.append({"functionResponse": reply})
history.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool-call limit reached before a final answer.")
Uruchom python order_agent.py. Ostateczna odpowiedź powinna odzwierciedlać lokalny rekord dla DEMO-1001. W prawdziwej usłudze autoryzuj użytkownika przed dostępem do zamówienia; wybór identyfikatora zamówienia przez model nie jest dowodem uprawnień.
Ile kosztuje Gemini 4 Hydrogen API?
Poniższe stawki są w USD za milion tokenów, sprawdzone 17 listopada 2026 r. Porównują standardowe niebuforowane wejście i wyjście, nie obejmują wsadów, priorytetu, buforowanego wejścia ani oddzielnie rozliczanych narzędzi.
| Typ tokenu | Google Global Standard | Gemini 4 Hydrogen API w CometAPI |
|---|---|---|
| Tokeny wejściowe / 1M | $1.50 | $1.20 |
| Tokeny wyjściowe / 1M | $7.50 | $6.00 |
Dla 100 000 tokenów wejściowych i 10 000 rozliczanych tokenów wyjściowych, szacunek CometAPI wynosi 0.1 × $1.20 + 0.01 × $6.00 = $0.18. Te same wolumeny przy standardowych stawkach Google kosztują $0.225, czyli różnicę 20%. Uwzględnij tokeny rozumowania w zużyciu wyjścia i sprawdzaj rozliczone użycie na swoim koncie przy szacowaniu rzeczywistego przepływu pracy.
Jak migrować do Gemini 4 Hydrogen API?
Co zmienia się przy migracji z Gemini 3.8 Flash?
Zanim zmienisz identyfikator modelu, sprawdź ustawienie rozumowania, budżet kontekstu i historię rozmowy, którą klient wysyła z każdym żądaniem.
| Szczegół integracji | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| Domyślny poziom rozumowania | MEDIUM | HIGH |
| Rozliczanie kontekstu | Oddzielne limity wejścia i wyjścia | Jeden wspólny budżet wejścia/wyjścia |
| Stan wieloturnowy | Przejrzyj obsługę historii w istniejącym kliencie | Zachowuj kompletne części modelu i podpisy; edycje prefiksu wymagają specjalnej obsługi |
Udokumentowane zmiany migracji mają największe znaczenie, gdy Twoja aplikacja polega na domyślnych ustawieniach, kompresuje historię lub wykonuje kilka tur z narzędziami. Ustaw rozumowanie jawnie i przetestuj krótki istniejący przepływ przed zmianą modelu produkcyjnego.
Zaktualizuj istniejącą integrację
Utwórz konfigurację testową z nowym identyfikatorem modelu, zachowując razem jego klucz i endpoint. Uruchom ten sam reprezentatywny przepływ w obu konfiguracjach, aby porównać ich zachowanie.
- Wyślij nowe żądanie tekstowe i zweryfikuj powód zakończenia oraz zużycie tokenów.
- Odtwórz zadanie wieloturnowe i rundę narzędzia, używając kompletnych obiektów odpowiedzi modelu.
- Usuń niekompatybilne sterowania wymienione w sekcji ograniczeń przed porównywaniem wyników żądań.
- Przećwicz ścieżkę wycofania w nowej rozmowie; nie zakładaj, że inny model przyjmie zapisane metadane rozumowania Hydrogen.
Zdecyduj, czy migracja pomaga Twojemu obciążeniu
Przyjmij nową konfigurację, gdy spełnia cele jakości i opóźnień zadania przy akceptowalnym koszcie na ukończone zadanie. Jeśli obecny klient już spełnia te cele, zastosuj ograniczony pilotaż, aby potwierdzić korzyści przed przeniesieniem wszystkich żądań. Zachowaj spójność promptów, danych wejściowych i kryteriów oceny podczas ewaluacji.
Ograniczenia Gemini 4 Hydrogen API
Przewodnik deweloperski Hydrogen opisuje ograniczenia wpływające na istniejących klientów. Rozwiązuj je w konstrukcji żądania zamiast ponawiać to samo odrzucone żądanie.
- Nieobsługiwane pola: usuń thinkingBudget, thinkingLevel ustawione na MINIMAL, frequencyPenalty, presencePenalty oraz candidateCount większe niż jeden.
- Ignorowane ustawienia próbkowania: niestandardowe temperature, topP i topK nie sterują wyjściem Hydrogen.
- Buforowanie: jawne cachedContent jest nieobsługiwane. Stabilne prefiksy promptów mogą używać buforowania niejawnego, ale nie oznacza to zniżki na buforowanie specyficznej dla bramki.
- Długie wyjście: przykładowy klient w tym przewodniku implementuje tylko żądanie synchroniczne. Nie obejmuje długiego dekodowania w tle ani specyficznych dla dostawcy przepływów kontynuacji.
- Zmiany w rozmowie: modyfikowanie wcześniejszych promptów lub definicji narzędzi może unieważnić stan rozumowania. Zachowaj prefiks lub zaimplementuj udokumentowane zachowanie w przypadku niedopasowania prefiksu dla wybranej trasy.
Typowe kontrolki konfiguracji
| Objaw | Pierwsza kontrola |
|---|---|
| 401 lub 403 | Potwierdź, że dane logowania należą do endpointu i mają dostęp do wybranego modelu. |
| 400 | Przeczytaj treść błędu; sprawdź nieobsługiwane pola, błędny JSON i metadane rozmowy. |
| Brak widocznego tekstu | Sprawdź promptFeedback, części kandydata i finishReason; odpowiedź może być zablokowana, niekompletna lub żądać narzędzia. |
| MAX_TOKENS | Traktuj tekst jako potencjalnie niekompletny i przejrzyj budżet wyjścia przed jego akceptacją. |
| Odrzucono żądanie pliku | Zweryfikuj faktyczny typ MIME i limit ładunku dla wybranej trasy. |
W przypadku nieoczekiwanych awarii zapisuj model, trasę, status, znacznik czasu i identyfikator żądania, gdy jest dostępny. Nie umieszczaj kluczy API i wrażliwych treści plików w rutynowych logach.
FAQ
Jak ponawiać błędy limitu szybkości Gemini 4 Hydrogen API?
Dla HTTP 429 zmniejsz współbieżność i ponawiaj z wykładniczym wycofywaniem oraz jitterem, z ustaloną maksymalną liczbą prób. Zachowaj identyfikator żądania, gdy bramka go dostarcza. Nie ponawiaj nieprawidłowych żądań ani błędów uwierzytelnienia bez zmian; przewodnik po błędach i ponawianiu CometAPI rozróżnia je od awarii przejściowych. Limit czasu może wystąpić po rozpoczęciu przetwarzania, więc chroń wszelkie działania po stronie aplikacji przed podwójnym wykonaniem.
Czy mogę wywoływać Gemini 4 Hydrogen API bezpośrednio z aplikacji webowej?
Kieruj żądania przez własny backend. Klucz osadzony w JavaScript po stronie frontendu może zostać wyodrębniony przez odwiedzających, nawet jeśli kod jest zbudowany lub zminifikowany. Pozwól backendowi uwierzytelniać użytkowników, stosować limity użycia i wysyłać żądanie do modelu. Dla strumieniowania przekazuj odpowiedź przyrostową do przeglądarki bez ujawniania klucza API do usługi upstream.
Jak obsłużyć przerwany strumień Gemini 4 Hydrogen?
Traktuj otrzymany tekst jako wynik częściowy, dopóki odpowiedź nie zostanie ukończona. Nowe żądanie rozpoczyna nową generację; nie wznawia automatycznie przerwanego strumienia w tym samym tokenie. Przechowuj częściowe wyjście oddzielnie od ponowionej odpowiedzi i nie wykonuj akcji na podstawie niekompletnego JSON lub niedokończonych argumentów narzędzi. Zaproponuj widoczną akcję ponowienia zamiast cichego konkatenowania dwóch generacji.
Zakończenie
Użyj reprezentatywnego zadania jako pierwszego testu akceptacyjnego: żądanie powinno się powieść, aplikacja powinna wyodrębnić zamierzony wynik, a zarejestrowane zużycie tokenów powinno mieścić się w Twoim budżecie. Dodawaj po jednej funkcji naraz i utrzymuj ten test w zestawie integracyjnym. Mały, obserwowalny klient jest łatwiejszy do rozszerzania niż duży przepływ pracy, którego awarie trudno prześledzić.

