Référence de l'API

API Gemini : texte et vidéo avec BetterToken

Appelez Gemini via OpenAI Chat Completions ou l’API native Gemini de BetterToken. Authentification, SDK, streaming, outils, entrée vidéo et résolution des erreurs.

Utilisez gemini-3.8-flash et gemini-4-argon avec votre BetterToken API Key. Les deux interfaces prennent en charge le texte, la vidéo, le streaming et les appels d’outils avec renvoi des résultats.

Choisir une interface

Interface	Base URL	Quand l’utiliser
Compatible OpenAI	`https://bettertoken.ai/v1`	Votre application utilise Chat Completions ou le SDK OpenAI.
Native Gemini	`https://bettertoken.ai`	Votre application utilise les champs Gemini ou les SDK Google GenAI.

Tous les exemples utilisent gemini-3.8-flash. Remplacez-le par gemini-4-argon pour utiliser l’autre modèle. Consultez les tarifs actuels dans le catalogue de modèles. Pour générer des images, consultez le guide Nano Banana.

Authentification

Créez une BetterToken API Key, puis remplacez YOUR_API_KEY ci-dessous. Exécutez cette commande dans le même terminal que les exemples.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Interface	Authentification
Compatible OpenAI	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Native Gemini	`x-goog-api-key: $BETTERTOKEN_API_KEY` (recommandé) ou `Authorization: Bearer $BETTERTOKEN_API_KEY`

Une clé Google AI Studio ne fonctionne pas ici. Utilisez votre BetterToken API Key. L’interface native accepte aussi ?key=, mais évitez cette méthode : les URL peuvent apparaître dans les journaux.

Interface compatible OpenAI

Envoyez les requêtes à POST https://bettertoken.ai/v1/chat/completions. Pour les SDK, utilisez la Base URL https://bettertoken.ai/v1 ; le SDK ajoute /chat/completions.

curl : requête de base

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."}]
  }'

Lisez le texte dans choices[0].message.content. Pour le streaming avec curl, ajoutez "stream": true au corps JSON et utilisez curl --no-buffer.

Python : requête de base et streaming

Installez le SDK OpenAI dans votre environnement Python, puis exécutez l’exemple.

python -m pip install openai

La requête de streaming utilise stream=True. Lisez le texte dans choices[0].delta.content pour chaque fragment.

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()

Appels d’outils

Déclarez les fonctions dans tools avec type: "function", un nom name et un JSON Schema dans parameters. Lorsque l’assistant renvoie tool_calls, exécutez les fonctions demandées dans votre application.

Conservez le message complet de l’assistant, y compris tool_calls, dans la conversation. Ajoutez un message role: "tool" pour chaque résultat. Utilisez l’identifiant d’appel correspondant dans tool_call_id et le résultat dans content. Renvoyez les messages et tools mis à jour à Chat Completions.

Pour envoyer une image sur cette interface, utilisez une partie image_url avec une URL HTTP ou une data URL, comme pour les autres modèles.

Interface native Gemini

Pour les SDK Google GenAI, définissez la Base URL sur https://bettertoken.ai. N’ajoutez pas /v1beta : le SDK l’ajoute. Les requêtes HTTP directes utilisent les chemins complets ci-dessous.

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."}]}]
  }'

Lisez le texte dans candidates[].content.parts[].text.

curl : streaming

streamGenerateContent?alt=sse renvoie des événements Server-Sent Events (SSE). --no-buffer affiche les événements dès leur réception.

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 : SDK Google GenAI

Installez google-genai dans votre environnement Python. L’exemple envoie une requête de base, puis une requête de streaming.

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 : SDK Google GenAI

Installez @google/genai. Enregistrez l’exemple JavaScript dans gemini.mjs, puis exécutez node gemini.mjs.

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();

Appels d’outils

Déclarez les fonctions dans tools[].functionDeclarations. Lisez la fonction et ses arguments dans functionCall, au sein des parties de réponse du modèle, puis exécutez-la dans votre application.

Conservez le contenu complet du modèle dans contents. Ajoutez une entrée role: "user" dont les parts contiennent functionResponse avec le name de la fonction et un objet response contenant le résultat. Renvoyez les contents et tools mis à jour à generateContent.

Lister les modèles

Utilisez GET https://bettertoken.ai/v1beta/models pour lister les modèles.

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

Entrée vidéo

Avant d’envoyer un exemple, remplacez REPLACE_WITH_VIDEO_BASE64 par le base64 de votre vidéo sur une seule ligne. Les exemples utilisent un clip MP4 ; pour un autre format, modifiez le type MIME et le nom du fichier.

Types MIME acceptés : video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/wmv, video/flv, video/mpegps.

Envoyez la vidéo en base64 intégré au corps de la requête. Le base64 augmente le volume d’environ un tiers par rapport au fichier. Utilisez des clips courts ou compressés ; les requêtes trop volumineuses peuvent renvoyer HTTP 413.

Le champ file.file_data de l’interface compatible OpenAI inclut le préfixe data:video/mp4;base64,. Dans l’interface native, inlineData.data contient uniquement le base64, sans ce préfixe.

Chat Completions : fichier intégré

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

Gemini natif : 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

Utilisation et facturation

Chat Completions : les tokens de raisonnement sont inclus dans completion_tokens et facturés en sortie.

Gemini natif : usageMetadata.thoughtsTokenCount est facturé en sortie. cachedContentTokenCount indique l’entrée en cache. La vidéo compte comme tokens d’entrée ; promptTokensDetails l’identifie avec la modalité VIDEO.

Limites

POST /v1/responses ne prend pas en charge ces modèles Gemini. Codex CLI et les clients utilisant uniquement Responses API ne peuvent pas les appeler. Utilisez Chat Completions ou l’interface native.
Les références file_id et les envois Google File API via fileData.fileUri ne sont pas pris en charge. Envoyez la vidéo en base64 intégré.

Résolution des erreurs

Erreur	Action
`401`	Vérifiez la BetterToken API Key et l’en-tête d’authentification. Ajoutez la clé manquante ou remplacez la clé incorrecte.
`413`	Le corps de la requête est trop volumineux. Raccourcissez ou compressez la vidéo.
`429`	Limite de fréquence ou manque temporaire de capacité chez le fournisseur. Réessayez avec des délais croissants.
`503` avec `model_not_found`	Aucune capacité n’est disponible pour le moment. Réessayez plus tard.

Pour les autres erreurs, consultez les erreurs API.