跳转到内容
简体中文
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
免费注册
接口文档

Gemini API：通过 BetterToken 调用文本和视频模型

通过 BetterToken 的 OpenAI Chat Completions 或 Gemini 原生 API 调用 Gemini。包含认证、SDK、流式输出、工具调用、视频输入与排错说明。

使用你的 BetterToken API Key 调用 gemini-3.8-flash 和 gemini-4-argon。两种接口都支持文本、视频、流式输出，以及工具调用和返回工具结果。

选择接口

接口Base URL适用情况
OpenAI-compatiblehttps://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-compatibleAuthorization: Bearer $BETTERTOKEN_API_KEY
Gemini 原生x-goog-api-key: $BETTERTOKEN_API_KEY（推荐），或 Authorization: Bearer $BETTERTOKEN_API_KEY

这里不能使用 Google AI Studio Key，请使用 BetterToken API Key。原生接口也接受 ?key=，但 URL 可能被写入日志，因此建议使用请求头。

OpenAI-compatible 接口

将请求发送到 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 示例。

终端窗口
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 后，由你的应用执行对应函数。

将完整的 assistant 消息保留在对话中，包括 tool_calls。为每个结果追加一条 role: "tool" 消息。将 tool_call_id 设为对应的调用 ID，并把结果写入 content。再将更新后的 messages 和 tools 发给 Chat Completions。

该接口的图片输入使用 image_url 内容项，可填写 HTTP URL 或 data 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 返回服务器发送事件（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 会使请求体比原文件大约三分之一。建议使用较短或压缩后的片段；过大的请求可能返回 HTTP 413。

OpenAI-compatible 的 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：**推理／思考 token 包含在 completion_tokens 中，按输出计费。

Gemini 原生：usageMetadata.thoughtsTokenCount 按输出计费。cachedContentTokenCount 表示缓存输入。视频计入输入 token；promptTokensDetails 通过模态 VIDEO 标识视频。

使用限制

  • POST /v1/responses 不支持这些 Gemini 模型。Codex CLI 和其他仅使用 Responses API 的客户端无法调用它们。请使用 Chat Completions 或原生接口。
  • 不支持 file_id 引用，也不支持使用 fileData.fileUri 的 Google File API 上传。请以内联 base64 发送视频。

常见问题

错误处理方式
401检查 BetterToken API Key 和认证请求头。补全或替换错误的 Key。
413请求体过大。缩短或压缩视频。
429触发限流，或上游暂时容量不足。逐步延长间隔后重试。
503 且代码为 model_not_found当前没有可用容量。请稍后重试。

其他错误请参阅 API 错误说明。