---
title: Gemini API 快速入门
description: "Gemini API 快速入门：通过 apiToken.sale 发起首个请求——用 curl 或 Google GenAI SDK 调用原生 generateContent，x-goog-api-key 鉴权、SSE 流式输出和显式 model ID。"
url: https://apitoken.sale/zh/docs/learn/gemini-api-quickstart
language: zh-CN
---

# Gemini API 快速入门：用 curl 和 Google GenAI SDK 发起首个请求

这份 Gemini API 快速入门带你在几分钟内跑通第一个可用请求：先对原生 generateContent 路由发一个 curl，再用官方 Google GenAI SDK（Python 或 JavaScript）完成同样的调用。只需改动 base URL 和密钥请求头——请求结构、流式输出和 usage 元数据与 Google 文档完全一致。

## 一个端点，原生 Gemini 协议

要通过 apiToken.sale 发起第一个 Gemini API 请求，完全保留 Google 官方协议，只改两个值：base URL 换成 https://router.apitoken.sale，密钥换成你的 apiToken.sale 密钥，通过 x-goog-api-key 请求头发送。每个请求和响应都保持原生 generateContent 结构，因此 Google 官方文档、SDK 示例以及你现有的 Gemini 代码都可以原样使用。

一个密钥、一份预付余额覆盖所有支持的提供商——Gemini 与 Claude、GPT、Kimi 并列可用。Gemini 用量按 Google 官方 token 费率计量，从余额扣费前先应用固定 50% 折扣。你这边不需要任何 Google Cloud 项目或计费账户。

## 创建密钥并查看你的模型目录

1. 免费注册 apiToken.sale 账号并打开控制台——无需审批，没有 waitlist。
2. 生成一个 API 密钥。它形如 sk-pool-…，对 Gemini、Claude、GPT 和 Kimi 同样有效。
3. 用银行卡或加密货币充值任意整数美元金额；预付余额永不过期。
4. 将密钥导出为 APITOKEN_API_KEY，然后列出你的密钥实际可调用的模型：

```
curl https://router.apitoken.sale/v1beta/models \
  -H "x-goog-api-key: $APITOKEN_API_KEY"
```

从返回结果中挑一个显式的 model ID。gemini-3.6-flash 是首次文本调用的合适默认；客户端库内置的默认模型可能不在网关目录中，而路由器只服务它列出的 ID。

## 首个请求：用 curl 调用 generateContent

```
curl https://router.apitoken.sale/v1beta/models/gemini-3.6-flash:generateContent \
  -H "x-goog-api-key: $APITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Reply with exactly: connected"}]}]}'
```

响应是标准的 Google 结构：读取 candidates[0].content.parts 并拼接其中的文本部分。同一份 JSON 还带有 usageMetadata，包含 prompt、candidate 和 total 的 token 计数，因此 token 与成本统计代码从第一次调用起就能工作。

发送大提示词之前，可以在同一模型路径上调用 :countTokens。它只返回 token 计数、不生成任何内容——在花钱生成之前免费估算输入量。

## 用 streamGenerateContent 流式输出 token

```
curl "https://router.apitoken.sale/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $APITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Count from one to five"}]}]}'
```

?alt=sse 查询参数把响应切换为 server-sent events：每个事件是同一 candidate 结构中的一个增量 chunk，最后一个事件携带汇总的 usageMetadata。在 SDK 中，同一路由对应 Python 的 generate_content_stream 和 JavaScript 的 generateContentStream。

凡是面向用户的输出都用流式，让首批 token 立即渲染。对于只关心最终文本的批处理任务，普通的 generateContent 更易于解析和重试。

## 官方 SDK：Python 和 JavaScript

```
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["APITOKEN_API_KEY"],
    http_options=types.HttpOptions(base_url="https://router.apitoken.sale"),
)

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Reply with exactly: connected",
)
print(response.text)
```

```
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.APITOKEN_API_KEY,
  httpOptions: { baseUrl: "https://router.apitoken.sale" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "Reply with exactly: connected",
});
console.log(response.text);
```

- 传裸 base URL https://router.apitoken.sale；SDK 配置中不要再附加 /v1beta。
- 传具体的 model ID，比如 gemini-3.6-flash——永远不要依赖客户端默认值。
- 把 APITOKEN_API_KEY 放在环境变量里，而不是写进源码。

> 如果 SDK 的每个请求都返回 404，检查请求路径里是否出现了重复的 /v1beta/v1beta 段。SDK 会自己拼接 API 版本；如果配置的 host 已包含 /v1beta，就会产生重复路径。

## 前几次调用的成本

Gemini 调用按 Google 官方费率项精确结算——输入、缓存输入和输出——再叠加固定 50% 折扣。常用文本模型折后每 100 万 token 的价格：

| 模型 | 每 100 万 token 输入 / 缓存 / 输出 | 适合的首个任务 |
| --- | --- | --- |
| gemini-3.6-flash | $0.375 / $0.0375 / $1.875 | 日常编程、聊天和智能体 |
| gemini-3.1-flash-lite | $0.125 / $0.0125 / $0.75 | 分类、抽取、路由 |
| gemini-2.5-flash-lite | $0.05 / $0.005 / $0.20 | 最便宜的大批量文本 |
| gemini-3.1-pro-preview | $1 / $0.10 / $6 | 最硬的推理和评审 |

[完整 Gemini 费率表，含长上下文与图像费率项](/docs/learn/gemini-api-pricing)

[所有支持的 model ID 与价格](/models)

## 排查首个响应的问题

| 状态码 | 可能原因 | 解决方法 |
| --- | --- | --- |
| 400 | 缺少或错误的 x-goog-api-key（INVALID_ARGUMENT，原因 API_KEY_INVALID），或本 endpoint 无法兑现的字段（FILE_URI_UNSUPPORTED / CACHED_CONTENT_UNSUPPORTED） | 核对密钥和请求头；文件用 inlineData；去掉 cachedContent |
| 404 | /v1beta 重复，或 model ID 不在目录中 | 传裸 host；从 GET /v1beta/models 中挑选 ID |
| 402 FAILED_PRECONDITION | 预付余额耗尽——HTTP 402，不是 RESOURCE_EXHAUSTED，也不是 429 | 在控制台充值任意整数美元金额 |

不要在原生 Gemini 路由上发送 Authorization: Bearer 或 Anthropic 的 x-api-key 请求头——x-goog-api-key 是它们接受的唯一凭据。由于线上协议格式不变，日后切回 Google 自己的端点只需改一行 base URL。

[在 Pro、Flash 和 Flash-Lite 之间如何选择](/docs/learn/gemini-pro-vs-flash-vs-flash-lite)

## 常见问题

### 官方 Google GenAI SDK 能配合 apiToken.sale 使用吗？

可以。在 Python 中设置 HttpOptions(base_url)、在 JavaScript 中设置 httpOptions.baseUrl 为 https://router.apitoken.sale，并传入 apiToken.sale 密钥；请求和响应结构保持原生。

### Gemini API 请求用哪个请求头鉴权？

x-goog-api-key，携带你的 sk-pool 密钥。原生 Gemini 路由不接受 Authorization: Bearer 或 Anthropic 的 x-api-key 请求头。

### 如何流式输出 Gemini 的内容？

用 x-goog-api-key 调用 /v1beta/models/{model}:streamGenerateContent?alt=sse，或使用 SDK 的 generate_content_stream / generateContentStream 方法。最后一个 SSE 事件携带汇总的 usageMetadata。

### 为什么重复的 /v1beta 会返回 404？

Google SDK 会在配置的 host 上自动追加 API 版本。只配置裸 host，最终请求中就只会有一个 /v1beta 段。

### 应该先调用哪个 Gemini 模型？

通用文本和编程任务从 gemini-3.6-flash 开始。批量分类迁移到 Flash-Lite 模型，最硬的推理任务交给 gemini-3.1-pro-preview。

### 调用 countTokens 免费吗？

免费。在模型路径上调用 :countTokens 只返回 token 计数、不做生成，因此可以在付费生成之前估算输入规模。

---
Get a key: https://apitoken.sale/register
More guides: https://apitoken.sale/zh/docs/learn