> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Gemini API

> 1 つの BeatAPI キーで、OpenAI、Anthropic、Gemini 互換 SDK から Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.1 Pro を利用できます。

# Gemini API

Gemini モデル 4 種を、他の Text API と同じパススルーで利用できます。4 つすべてのリクエスト形式に対応しています。Gemini 3.8 Flash には無料版もあります。

| モデル                      | 適した用途                                              |
| ------------------------ | -------------------------------------------------- |
| `gemini-3.8-flash`       | 最新世代の Flash。3.7 と同じ料金、同じ 1M コンテキスト                 |
| `gemini-3.7-flash`       | 以下の例で使用するモデル。高速・低価格で、価格に対して高い推論能力                  |
| `gemini-3.6-flash`       | 既に調整済みの処理パイプライン向けの前世代 Flash                        |
| `gemini-3.1-pro-preview` | 特に難しい推論や非常に長いコンテキストを扱う処理                           |
| `gemini-3.8-flash-free`  | `gemini-3.8-flash` の無料版。入力・出力ともに \$0 で、専用のレート制限を適用 |

> **Note**
>
> `gemini-3.8-flash-free` は `gemini-3.8-flash` の無料版で、以下の 4 つのリクエスト形式で同じように呼び出せます。無料で利用できますが、安定性は保証されません。いつでもレート制限が適用されたり、提供が終了したりする場合があり、提供期間も保証されません。1 日あたりの利用枠は動的に調整されます。無料モデルの上限は、アカウントごとに初回チャージ前が毎分 1 回の成功リクエスト、チャージ後が毎分 10 回です。

> **Warning**
>
> Gemini 3.x はデフォルトで推論を行い、**推論トークンを出力として課金します**。`max_tokens` は推論と画面に表示される回答を合わせた上限のため、予算が小さいと回答が途中で切れます。ある典型的なリクエストでは、`max_tokens: 150` のうち 142 トークンが推論に使われ、回答は 4 トークンでした。短い回答でも、出力予算を少なくとも 1,000 トークンに設定してください。

## 推奨：Gemini 互換のコンテンツ形式

`POST https://api.beatapi.io/v1beta/models/{model}:generateContent`

BeatAPI キーは `x-goog-api-key`、Bearer 認証、または Gemini SDK 互換の `key` クエリパラメーターで送信できます。HTTP を直接呼び出す実装では、ヘッダーの使用を推奨します。

```bash
curl --request POST \
  --url 'https://api.beatapi.io/v1beta/models/gemini-3.7-flash:generateContent' \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Design a resilient webhook retry strategy for a payments API."
        }
      ]
    }
  ]
}'
```

ストリーミングには `:streamGenerateContent` を使用してください。BeatAPI はイベントストリームを変換せずに転送します。

## 既存の SDK 形式

同じモデルを他の 3 つのリクエスト形式でも利用できます。既存の実装は、ベース URL を変更し、プロバイダーのキーを BeatAPI キーに置き換えることで移行できます。

### OpenAI Chat Completions

`POST https://api.beatapi.io/v1/chat/completions`

```bash
curl --request POST \
  --url https://api.beatapi.io/v1/chat/completions \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.7-flash",
  "messages": [
    {
      "role": "user",
      "content": "Design a resilient webhook retry strategy for a payments API."
    }
  ]
}'
```

推論トークンは `usage.completion_tokens_details.reasoning_tokens` に報告され、`completion_tokens` に含まれます。

### OpenAI Responses

`POST https://api.beatapi.io/v1/responses`

```bash
curl --request POST \
  --url https://api.beatapi.io/v1/responses \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.7-flash",
  "input": "Design a resilient webhook retry strategy for a payments API.",
  "reasoning": {
    "effort": "medium"
  }
}'
```

### Anthropic Messages

`POST https://api.beatapi.io/v1/messages`

```bash
curl --request POST \
  --url https://api.beatapi.io/v1/messages \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.7-flash",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Design a resilient webhook retry strategy for a payments API."
    }
  ]
}'
```

## キャッシュ

キャッシュ入力トークンは通常の入力料金の 10 分の 1 で課金され、`usage.prompt_tokens_details.cached_tokens` に報告されます。Google のコンテキストキャッシュ保存料金は請求されず、キャッシュ読み取りのみが課金対象です。

## 認証と利用可能なモデル

本番導入前に、現在有効なテキストモデルの一覧を確認してください。

```bash
curl https://api.beatapi.io/v1/models \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    { "id": "gemini-3.7-flash", "object": "model", "owned_by": "beatapi" }
  ]
}
```

Text、Image、Video、Workflow、Effect、Realtime API は、同じ API キーと USD 残高を共有します。呼び出しは実際のトークン使用量に基づいて課金されます。ダッシュボードの利用状況ログで、リクエスト ID、モデル、トークン総数、ステータス、精算額を確認できます。

## 本番運用前のチェックリスト

* 回答だけでなく、推論にも使われるトークンを出力予算に含めてください。
* API キーは信頼できるサーバーに保存し、ログには記録しないでください。
* リクエストのタイムアウトを明示的に設定し、ストリーミングレスポンスの再接続を安全に処理してください。
* サポートへの問い合わせや課金の確認に備え、レスポンスのリクエスト ID を記録してください。
* `401`、`402`、`403`、`404`、`429`、`503` はそれぞれ区別して処理し、再試行は `429`、`500`、`503` の場合にのみ行ってください。[エラー](/errors#text-endpoints)を参照してください。

## 画像・動画モデルの利用

同じ BeatAPI アカウントで [GPT-5.6](/text-api/gpt-5-6)、[Claude](/text-api/claude)、[Nano Banana 2](/image-api/nano-banana-2) をはじめ、その他の Image API・Video API を利用できます。別の課金・認証システムを追加する必要はありません。