Referência da API

API Gemini: texto e vídeo com BetterToken

Use o Gemini pelo OpenAI Chat Completions ou pela API nativa no BetterToken. Autenticação, SDKs, streaming, ferramentas, entrada de vídeo e solução de erros.

Use gemini-3.8-flash e gemini-4-argon com sua BetterToken API Key. As duas interfaces aceitam texto, vídeo, streaming e chamadas de ferramentas com envio dos resultados.

Escolha uma interface

Interface	Base URL	Quando usar
Compatível com OpenAI	`https://bettertoken.ai/v1`	Seu aplicativo usa Chat Completions ou o SDK da OpenAI.
Nativa do Gemini	`https://bettertoken.ai`	Seu aplicativo usa campos do Gemini ou SDKs do Google GenAI.

Todos os exemplos usam gemini-3.8-flash. Troque por gemini-4-argon para usar o outro modelo. Veja os preços atuais na praça de modelos. Para gerar imagens, consulte o guia do Nano Banana.

Autenticação

Crie uma BetterToken API Key e substitua YOUR_API_KEY abaixo. Execute no mesmo terminal dos exemplos.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Interface	Autenticação
Compatível com OpenAI	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Nativa do Gemini	`x-goog-api-key: $BETTERTOKEN_API_KEY` (recomendado) ou `Authorization: Bearer $BETTERTOKEN_API_KEY`

Uma chave do Google AI Studio não funciona aqui. Use sua BetterToken API Key. A interface nativa também aceita ?key=, mas evite esse formato porque as URLs podem aparecer em logs.

Interface compatível com OpenAI

Envie as solicitações para POST https://bettertoken.ai/v1/chat/completions. Nos SDKs, use a Base URL https://bettertoken.ai/v1; o SDK adiciona /chat/completions.

curl: solicitação 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."}]
  }'

Leia o texto em choices[0].message.content. Para streaming com curl, adicione "stream": true ao corpo JSON e use curl --no-buffer.

Python: solicitação básica e streaming

Instale o SDK da OpenAI no seu ambiente Python e execute o exemplo.

python -m pip install openai

A solicitação de streaming usa stream=True. Leia o texto em choices[0].delta.content de cada bloco.

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

Chamada de ferramentas

Declare funções em tools com type: "function", um nome name e um JSON Schema em parameters. Quando o assistente retornar tool_calls, execute as funções solicitadas no seu aplicativo.

Mantenha a mensagem completa do assistente, incluindo tool_calls, na conversa. Adicione uma mensagem role: "tool" para cada resultado. Use o ID da chamada correspondente em tool_call_id e o resultado em content. Envie novamente os messages e tools atualizados para Chat Completions.

Para imagens nessa interface, use uma parte image_url com uma URL HTTP ou data URL, como nos outros modelos.

Interface nativa do Gemini

Nos SDKs do Google GenAI, defina a Base URL como https://bettertoken.ai. Não adicione /v1beta: o SDK faz isso. As solicitações HTTP diretas usam os caminhos completos abaixo.

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

Leia o texto em candidates[].content.parts[].text.

curl: streaming

streamGenerateContent?alt=sse retorna eventos Server-Sent Events (SSE). --no-buffer mostra os eventos conforme chegam.

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

Instale google-genai no seu ambiente Python. O exemplo faz uma solicitação básica seguida de uma solicitação 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 do Google GenAI

Instale @google/genai. Salve o exemplo JavaScript como gemini.mjs e execute 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();

Chamada de ferramentas

Declare funções em tools[].functionDeclarations. Leia a função e os argumentos em functionCall, nas partes da resposta do modelo, e execute a função no seu aplicativo.

Mantenha o conteúdo completo do modelo em contents. Adicione uma entrada role: "user" cujos parts incluam functionResponse com o name da função e um objeto response com o resultado. Envie novamente os contents e tools atualizados para generateContent.

Listar modelos

Use GET https://bettertoken.ai/v1beta/models para listar os 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 qualquer exemplo, substitua REPLACE_WITH_VIDEO_BASE64 pelo base64 do seu vídeo em uma única linha. Os exemplos usam MP4; para outro formato, altere o tipo MIME e o nome do arquivo.

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

Envie o vídeo como base64 embutido no corpo da solicitação. O base64 aumenta o tamanho em cerca de um terço em relação ao arquivo. Use clipes curtos ou comprimidos; solicitações muito grandes podem retornar HTTP 413.

O campo file.file_data da interface compatível com OpenAI inclui o prefixo data:video/mp4;base64,. Na interface nativa, inlineData.data contém apenas base64, sem esse prefixo.

Chat Completions: arquivo embutido

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 e cobrança

Chat Completions: os tokens de raciocínio são incluídos em completion_tokens e cobrados como saída.

Gemini nativo: usageMetadata.thoughtsTokenCount é cobrado como saída. cachedContentTokenCount informa a entrada em cache. Vídeo conta como tokens de entrada; promptTokensDetails o identifica pela modalidade VIDEO.

Limitações

POST /v1/responses não aceita esses modelos Gemini. Codex CLI e clientes que usam apenas a Responses API não podem chamá-los. Use Chat Completions ou a interface nativa.
Referências file_id e uploads pela Google File API com fileData.fileUri não são aceitos. Envie o vídeo como base64 embutido.

Solução de erros

Erro	O que fazer
`401`	Confira a BetterToken API Key e o cabeçalho de autenticação. Adicione a chave ausente ou substitua a incorreta.
`413`	O corpo da solicitação é grande demais. Encurte ou comprima o vídeo.
`429`	Limite de solicitações ou falta temporária de capacidade do provedor. Tente novamente com intervalos crescentes.
`503` com `model_not_found`	Não há capacidade disponível no momento. Tente mais tarde.

Para outros erros, consulte erros da API.