API リファレンス

Gemini API：BetterToken でテキストと動画を利用する

BetterToken の OpenAI Chat Completions または Gemini ネイティブ API で Gemini を呼び出します。認証、SDK、ストリーミング、ツール、動画入力、エラー対処を解説します。

BetterToken API Key で gemini-3.8-flash と gemini-4-argon を呼び出せます。両インターフェースはテキスト、動画、ストリーミング、ツール呼び出しと結果の返送に対応しています。

インターフェースを選ぶ

インターフェース	Base URL	選ぶ場面
OpenAI 互換	`https://bettertoken.ai/v1`	アプリで Chat Completions または OpenAI SDK を使用する場合。
Gemini ネイティブ	`https://bettertoken.ai`	アプリで Gemini のリクエスト項目または Google GenAI SDK を使用する場合。

すべての例では gemini-3.8-flash を使用します。別のモデルを使う場合は gemini-4-argon に変更してください。最新料金はモデル広場で確認できます。画像生成については別の Nano Banana ガイドを参照してください。

認証

BetterToken API Key を作成し、以下の YOUR_API_KEY を置き換えてください。例を実行するのと同じターミナルで設定します。

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

インターフェース	認証方法
OpenAI 互換	`Authorization: Bearer $BETTERTOKEN_API_KEY`
Gemini ネイティブ	`x-goog-api-key: $BETTERTOKEN_API_KEY`（推奨）、または `Authorization: Bearer $BETTERTOKEN_API_KEY`

Google AI Studio のキーは使用できません。BetterToken API Key を使用してください。ネイティブインターフェースは ?key= も受け付けますが、URL がログに残る可能性があるため避けてください。

OpenAI 互換インターフェース

POST https://bettertoken.ai/v1/chat/completions にリクエストを送信します。SDK の Base URL は https://bettertoken.ai/v1 です。SDK が /chat/completions を追加します。

curl：基本リクエスト

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

choices[0].message.content からテキストを読み取ります。curl でストリーミングを使うには、JSON 本文に "stream": true を追加し、curl --no-buffer を使用します。

Python：基本リクエストとストリーミング

Python 環境に OpenAI SDK をインストールしてから、例を実行してください。

python -m pip install openai

ストリーミングリクエストでは stream=True を指定します。各チャンクの choices[0].delta.content からテキストを読み取ります。

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

ツール呼び出し

tools に type: "function"、関数名 name、parameters 内の JSON Schema を指定して関数を宣言します。assistant が tool_calls を返したら、アプリで指定された関数を実行します。

tool_calls を含む assistant メッセージ全体を会話に保持します。各結果を role: "tool" メッセージとして追加します。tool_call_id に対応する呼び出し ID、content に結果を設定します。更新した messages と tools を Chat Completions に再送信します。

このインターフェースの画像入力には、他のモデルと同様に、HTTP URL または data URL を指定した image_url コンテンツ項目を使用します。

Gemini ネイティブインターフェース

Google GenAI SDK の Base URL は https://bettertoken.ai に設定します。/v1beta は追加しないでください。SDK が追加します。直接 HTTP リクエストを送る場合は、以下の完全なパスを使用します。

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

candidates[].content.parts[].text からテキストを読み取ります。

curl：ストリーミング

streamGenerateContent?alt=sse は Server-Sent Events（SSE）を返します。--no-buffer でイベントの到着時に表示します。

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

Python 環境に google-genai をインストールします。例では基本リクエストの後にストリーミングリクエストを送信します。

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

@google/genai をインストールします。JavaScript の例を gemini.mjs として保存し、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();

ツール呼び出し

tools[].functionDeclarations に関数を宣言します。モデルの応答パーツにある functionCall から関数と引数を読み取り、アプリで実行します。

モデルのコンテンツ全体を contents に保持します。role: "user" のエントリを追加し、その parts に functionResponse を含めます。対応する関数の name と、結果を含む response オブジェクトを指定します。更新した contents と tools を generateContent に再送信します。

モデル一覧

GET https://bettertoken.ai/v1beta/models でモデルを一覧表示します。

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

動画入力

いずれの例も、送信前に REPLACE_WITH_VIDEO_BASE64 を動画の単一行 base64 に置き換えてください。例では MP4 を使います。別の形式の場合は MIME タイプとファイル名も変更してください。

対応する MIME タイプ：video/mp4、video/mpeg、video/mpg、video/mov、video/avi、video/wmv、video/flv、video/mpegps。

動画はリクエスト本文に base64 として埋め込んで送信します。base64 によりデータ量は元のファイルより約 3 分の 1 増えます。短い動画や圧縮した動画を使用してください。大きすぎるリクエストは HTTP 413 を返すことがあります。

OpenAI 互換の file.file_data には data:video/mp4;base64, 接頭辞を含めます。ネイティブの inlineData.data には接頭辞なしの base64 のみを指定します。

Chat Completions：インラインファイル

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 ネイティブ：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

使用量と課金

**Chat Completions：**推論・思考トークンは completion_tokens に含まれ、出力として課金されます。

Gemini ネイティブ：usageMetadata.thoughtsTokenCount は出力として課金されます。cachedContentTokenCount はキャッシュされた入力を示します。動画は入力トークンとして計上され、promptTokensDetails ではモダリティ VIDEO で示されます。

制限事項

POST /v1/responses はこれらの Gemini モデルに対応していません。Codex CLI など Responses API のみを使うクライアントからは呼び出せません。Chat Completions またはネイティブインターフェースを使用してください。
file_id 参照と fileData.fileUri を使う Google File API のアップロードには対応していません。動画をインライン base64 で送信してください。

トラブルシューティング

エラー	対処方法
`401`	BetterToken API Key と認証ヘッダーを確認します。キーがない場合は追加し、誤っている場合は置き換えてください。
`413`	リクエスト本文が大きすぎます。動画を短くするか圧縮してください。
`429`	レート制限、または上流の一時的な容量不足です。待機時間を徐々に延ばして再試行してください。
`503`、コード `model_not_found`	現在利用可能な容量がありません。時間をおいて再試行してください。

その他のエラーは API エラーを参照してください。