API-Referenz

Gemini API: Text und Video mit BetterToken

Nutze Gemini über OpenAI Chat Completions oder die native Gemini API bei BetterToken. Authentifizierung, SDKs, Streaming, Tools, Videoeingabe und Fehlerbehebung.

Rufe gemini-3.8-flash und gemini-4-argon mit deinem BetterToken API Key auf. Beide Schnittstellen unterstützen Text, Video, Streaming sowie Tool-Aufrufe und die Rückgabe der Ergebnisse.

Schnittstelle wählen

Schnittstelle	Base URL	Wann verwenden
OpenAI-kompatibel	`https://bettertoken.ai/v1`	Deine Anwendung nutzt Chat Completions oder das OpenAI SDK.
Natives Gemini	`https://bettertoken.ai`	Deine Anwendung nutzt Gemini-Anfragefelder oder Google GenAI SDKs.

Alle Beispiele verwenden gemini-3.8-flash. Ersetze die ID durch gemini-4-argon, um das andere Modell zu nutzen. Aktuelle Preise findest du im Modellkatalog. Für die Bilderzeugung nutze die separate Nano Banana-Anleitung.

Authentifizierung

Erstelle einen BetterToken API Key und ersetze unten YOUR_API_KEY. Führe den Befehl im selben Terminal wie die Beispiele aus.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Schnittstelle	Authentifizierung
OpenAI-kompatibel	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Natives Gemini	`x-goog-api-key: $BETTERTOKEN_API_KEY` (empfohlen) oder `Authorization: Bearer $BETTERTOKEN_API_KEY`

Ein Google AI Studio-Schlüssel funktioniert hier nicht. Verwende deinen BetterToken API Key. Die native Schnittstelle akzeptiert auch ?key=. Vermeide dies, da URLs in Protokollen erscheinen können.

OpenAI-kompatible Schnittstelle

Sende Anfragen an POST https://bettertoken.ai/v1/chat/completions. SDKs verwenden die Base URL https://bettertoken.ai/v1 und hängen /chat/completions selbst an.

curl: einfache Anfrage

curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Explain why the sky is blue."}]
  }'

Lies den Text aus choices[0].message.content. Für Streaming mit curl ergänze "stream": true im JSON-Body und verwende curl --no-buffer.

Python: einfache Anfrage und Streaming

Installiere das OpenAI SDK in deiner Python-Umgebung und führe dann das Beispiel aus.

python -m pip install openai

Die Streaming-Anfrage verwendet stream=True. Lies den Text aus choices[0].delta.content jedes Blocks.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
)
messages = [{"role": "user", "content": "Explain why the sky is blue."}]

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
)
print(response.choices[0].message.content)

stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

Tool-Aufrufe

Deklariere Funktionen in tools mit type: "function", einem Funktionsnamen name und einem JSON Schema in parameters. Wenn der Assistent tool_calls zurückgibt, führe die angeforderten Funktionen in deiner Anwendung aus.

Bewahre die vollständige Assistentennachricht einschließlich tool_calls im Gespräch auf. Ergänze für jedes Ergebnis eine Nachricht mit role: "tool". Setze tool_call_id auf die passende Aufruf-ID und schreibe das Ergebnis in content. Sende die aktualisierten messages und tools erneut an Chat Completions.

Verwende für Bildeingaben in dieser Schnittstelle einen image_url-Inhaltsteil mit HTTP-URL oder data URL, wie bei anderen Modellen.

Native Gemini-Schnittstelle

Setze für Google GenAI SDKs die Base URL auf https://bettertoken.ai. Füge /v1beta nicht hinzu: Das SDK ergänzt es. Direkte HTTP-Anfragen verwenden die vollständigen Pfade unten.

curl: generateContent

curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

Lies den Text aus candidates[].content.parts[].text.

curl: Streaming

streamGenerateContent?alt=sse liefert Server-Sent Events (SSE). --no-buffer zeigt Ereignisse sofort nach ihrem Eingang an.

curl --fail-with-body --no-buffer \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

Python: Google GenAI SDK

Installiere google-genai in deiner Python-Umgebung. Das Beispiel sendet zuerst eine einfache Anfrage, danach eine Streaming-Anfrage.

python -m pip install google-genai

import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    http_options=types.HttpOptions(base_url="https://bettertoken.ai"),
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
)
print(response.text)

for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
):
    print(chunk.text or "", end="", flush=True)
print()

Node.js: Google GenAI SDK

Installiere @google/genai. Speichere das JavaScript-Beispiel als gemini.mjs und führe node gemini.mjs aus.

npm install @google/genai

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  httpOptions: { baseUrl: "https://bettertoken.ai" },
});

const response = await client.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
console.log(response.text);

const stream = await client.models.generateContentStream({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}
console.log();

Tool-Aufrufe

Deklariere Funktionen in tools[].functionDeclarations. Lies Funktion und Argumente aus functionCall in den Antwortteilen des Modells und führe die Funktion in deiner Anwendung aus.

Bewahre den vollständigen Modellinhalt in contents auf. Ergänze einen Eintrag mit role: "user", dessen parts eine functionResponse enthalten. Gib den passenden Funktionsnamen name und ein response-Objekt mit dem Ergebnis an. Sende die aktualisierten contents und tools erneut an generateContent.

Modelle auflisten

Verwende GET https://bettertoken.ai/v1beta/models, um Modelle aufzulisten.

curl --fail-with-body "https://bettertoken.ai/v1beta/models" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY"

Videoeingabe

Ersetze vor dem Senden eines Beispiels REPLACE_WITH_VIDEO_BASE64 durch die einzeiligen Base64-Daten deines Videos. Die Beispiele verwenden MP4. Passe bei anderen Formaten MIME-Typ und Dateinamen an.

Akzeptierte MIME-Typen: video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/wmv, video/flv, video/mpegps.

Sende Videos als eingebettete Base64-Daten im Anfrage-Body. Base64 vergrößert die Datenmenge gegenüber der Datei um etwa ein Drittel. Verwende kurze oder komprimierte Clips; sehr große Anfragen können HTTP 413 zurückgeben.

Bei der OpenAI-kompatiblen Schnittstelle enthält file.file_data das Präfix data:video/mp4;base64,. Natives inlineData.data enthält nur Base64 ohne dieses Präfix.

Chat Completions: eingebettete Datei

curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gemini-3.8-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "file", "file": {
        "filename": "clip.mp4",
        "file_data": "data:video/mp4;base64,REPLACE_WITH_VIDEO_BASE64"
      }},
      {"type": "text", "text": "Describe what happens in this video."}
    ]
  }]
}
JSON

Natives Gemini: inlineData

curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "video/mp4", "data": "REPLACE_WITH_VIDEO_BASE64"}},
      {"text": "Describe what happens in this video."}
    ]
  }]
}
JSON

Verbrauch und Abrechnung

Chat Completions: Denk- und Reasoning-Tokens sind in completion_tokens enthalten und werden als Ausgabe berechnet.

Natives Gemini: usageMetadata.thoughtsTokenCount wird als Ausgabe berechnet. cachedContentTokenCount zeigt die zwischengespeicherte Eingabe. Videos zählen als Eingabe-Tokens; promptTokensDetails kennzeichnet sie mit der Modalität VIDEO.

Einschränkungen

POST /v1/responses unterstützt diese Gemini-Modelle nicht. Codex CLI und andere Clients, die ausschließlich die Responses API verwenden, können sie nicht aufrufen. Verwende Chat Completions oder die native Schnittstelle.
file_id-Referenzen und Google File API-Uploads mit fileData.fileUri werden nicht unterstützt. Sende Videos als eingebettete Base64-Daten.

Fehlerbehebung

Fehler	Maßnahme
`401`	Prüfe den BetterToken API Key und den Authentifizierungsheader. Ergänze den fehlenden oder ersetze den falschen Schlüssel.
`413`	Der Anfrage-Body ist zu groß. Kürze oder komprimiere das Video.
`429`	Ratenbegrenzung oder vorübergehender Kapazitätsmangel beim Anbieter. Wiederhole die Anfrage mit zunehmenden Wartezeiten.
`503` mit `model_not_found`	Derzeit ist keine Kapazität verfügbar. Versuche es später erneut.

Weitere Fehler findest du unter API-Fehler.