Referencia de la API

API de Gemini: texto y vídeo con BetterToken

Usa Gemini con OpenAI Chat Completions o la API nativa de Gemini en BetterToken. Autenticación, SDK, streaming, herramientas, entrada de vídeo y solución de errores.

Usa gemini-3.8-flash y gemini-4-argon con tu BetterToken API Key. Las dos interfaces admiten texto, vídeo, streaming y llamadas a herramientas con devolución de resultados.

Elige una interfaz

Interfaz	Base URL	Cuándo usarla
Compatible con OpenAI	`https://bettertoken.ai/v1`	Tu aplicación usa Chat Completions o el SDK de OpenAI.
Nativa de Gemini	`https://bettertoken.ai`	Tu aplicación usa campos de Gemini o los SDK de Google GenAI.

Todos los ejemplos usan gemini-3.8-flash. Sustitúyelo por gemini-4-argon para usar el otro modelo. Consulta los precios actuales en la plaza de modelos. Para generar imágenes, consulta la guía de Nano Banana.

Autenticación

Crea una BetterToken API Key y sustituye YOUR_API_KEY abajo. Ejecuta el comando en el mismo terminal que los ejemplos.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Interfaz	Autenticación
Compatible con OpenAI	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Nativa de Gemini	`x-goog-api-key: $BETTERTOKEN_API_KEY` (recomendado) o `Authorization: Bearer $BETTERTOKEN_API_KEY`

Una clave de Google AI Studio no funciona aquí. Usa tu BetterToken API Key. La interfaz nativa también acepta ?key=, pero evítalo porque las URL pueden aparecer en los registros.

Interfaz compatible con OpenAI

Envía las solicitudes a POST https://bettertoken.ai/v1/chat/completions. En los SDK, usa la Base URL https://bettertoken.ai/v1; el SDK añade /chat/completions.

curl: solicitud básica

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

Lee el texto de choices[0].message.content. Para usar streaming con curl, añade "stream": true al cuerpo JSON y usa curl --no-buffer.

Python: solicitud básica y streaming

Instala el SDK de OpenAI en tu entorno Python y ejecuta el ejemplo.

python -m pip install openai

La solicitud de streaming usa stream=True. Lee el texto de choices[0].delta.content en cada fragmento.

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

Llamadas a herramientas

Declara las funciones en tools con type: "function", un nombre name y un JSON Schema en parameters. Cuando el asistente devuelva tool_calls, ejecuta las funciones solicitadas en tu aplicación.

Conserva el mensaje completo del asistente, incluido tool_calls, en la conversación. Añade un mensaje role: "tool" por resultado. Usa el ID de la llamada correspondiente en tool_call_id y el resultado en content. Envía de nuevo los messages y tools actualizados a Chat Completions.

Para enviar imágenes en esta interfaz, usa una parte image_url con una URL HTTP o data URL, igual que con otros modelos.

Interfaz nativa de Gemini

En los SDK de Google GenAI, usa la Base URL https://bettertoken.ai. No añadas /v1beta: el SDK lo añade. Las solicitudes HTTP directas usan las rutas completas de abajo.

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

Lee el texto de candidates[].content.parts[].text.

curl: streaming

streamGenerateContent?alt=sse devuelve eventos Server-Sent Events (SSE). --no-buffer muestra los eventos a medida que llegan.

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 de Google GenAI

Instala google-genai en tu entorno Python. El ejemplo realiza una solicitud básica y después otra 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 de Google GenAI

Instala @google/genai. Guarda el ejemplo JavaScript como gemini.mjs y ejecuta 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();

Llamadas a herramientas

Declara las funciones en tools[].functionDeclarations. Lee la función y sus argumentos en functionCall, dentro de las partes de respuesta del modelo, y ejecútala en tu aplicación.

Conserva el contenido completo del modelo en contents. Añade una entrada role: "user" cuyos parts incluyan functionResponse con el name de la función y un objeto response con el resultado. Envía de nuevo los contents y tools actualizados a generateContent.

Listar modelos

Usa GET https://bettertoken.ai/v1beta/models para listar los modelos.

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

Entrada de vídeo

Antes de enviar cualquiera de los ejemplos, sustituye REPLACE_WITH_VIDEO_BASE64 por el base64 de tu vídeo en una sola línea. Los ejemplos usan MP4; para otro formato, cambia el tipo MIME y el nombre del archivo.

Tipos MIME aceptados: video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/wmv, video/flv, video/mpegps.

Envía el vídeo como base64 integrado en el cuerpo de la solicitud. Base64 aumenta el tamaño aproximadamente un tercio respecto al archivo. Usa clips cortos o comprimidos; las solicitudes muy grandes pueden devolver HTTP 413.

El campo file.file_data de la interfaz compatible con OpenAI incluye el prefijo data:video/mp4;base64,. En la interfaz nativa, inlineData.data solo contiene base64, sin ese prefijo.

Chat Completions: archivo integrado

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 nativo: 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

Uso y facturación

Chat Completions: los tokens de razonamiento se incluyen en completion_tokens y se facturan como salida.

Gemini nativo: usageMetadata.thoughtsTokenCount se factura como salida. cachedContentTokenCount indica la entrada en caché. El vídeo cuenta como tokens de entrada; promptTokensDetails lo identifica con la modalidad VIDEO.

Limitaciones

POST /v1/responses no admite estos modelos Gemini. Codex CLI y los clientes que solo usan Responses API no pueden llamarlos. Usa Chat Completions o la interfaz nativa.
No se admiten referencias file_id ni cargas de Google File API mediante fileData.fileUri. Envía el vídeo como base64 integrado.

Solución de errores

Error	Qué hacer
`401`	Revisa la BetterToken API Key y la cabecera de autenticación. Añade la clave si falta o sustituye la incorrecta.
`413`	El cuerpo de la solicitud es demasiado grande. Acorta o comprime el vídeo.
`429`	Límite de solicitudes o falta temporal de capacidad del proveedor. Reintenta con esperas crecientes.
`503` con `model_not_found`	No hay capacidad disponible en este momento. Reintenta más tarde.

Para otros errores, consulta errores de API.