# Google Gemini

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API |
> |---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Multimodal AI — chat, vision, PDF/document processing, thinking/reasoning, and embeddings.

**Category:** AI / LLM | **Website:** [ai.google.dev](https://ai.google.dev) | **Docs:** [ai.google.dev/gemini-api/docs](https://ai.google.dev/gemini-api/docs)

## Access Methods

| Method | Base URL | Auth |
|--------|----------|------|
| **x402 (Base)** | `https://gemini.x402.beta.paywithlocus.com/gemini/` | HTTP 402 auto-payment |
| **Wrapped API** | `https://api.beta.paywithlocus.com/api/wrapped/gemini/` | `Authorization: Bearer <LOCUS_API_KEY>` |

**OpenAPI discovery:** `GET https://gemini.x402.beta.paywithlocus.com/openapi.json`

## Endpoints

### Chat

Multimodal text generation — chat, vision (images), PDF/document processing, thinking/reasoning, and structured output. Supports all Gemini models.

**Estimated cost:** Model-dependent (~$0.003–$0.15)

**Payment:** x402 `upto` — the challenge amount is a maximum; the receipt contains the actual settled usage.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Gemini model ID (e.g. 'gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.0-flash', 'gemini-2.5-flash-lite', 'gemini-3-flash-preview', 'gemini-3.1-pro-preview') |
| `messages` | array | No | Conversation messages. Each: { role: "user"\|"model", content: "text" } or { role, parts: [{ text }, { inlineData: { mimeType, data } }] } for multimodal (images, PDFs) |
| `contents` | array | No | Native @google/genai contents array. Supports text, inlineData, and fileData parts. Use this OR messages. |
| `systemInstruction` | string | No | System instruction / system prompt |
| `maxOutputTokens` | number | Yes | Maximum output tokens (default 8192, max 65536) |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0) |
| `topP` | number | No | Nucleus sampling threshold |
| `topK` | number | No | Top-K sampling (default 64) |
| `thinking` | string \| boolean \| number | No | Enable thinking/reasoning. true for dynamic thinking, a number for exact token budget (2.5 models), or a level: 'minimal', 'low', 'medium', 'high'. Levels map to token budgets on 2.5 models and thinkingLevel on 3.x models. |
| `responseMimeType` | string | No | Response format: 'text/plain' (default) or 'application/json' for structured output |
| `responseJsonSchema` | object | No | JSON Schema for structured output (requires responseMimeType: application/json) |
| `stopSequences` | string[] | No | Stop sequences to end generation |

```bash
curl -X POST https://gemini.x402.beta.paywithlocus.com/gemini/chat \
  -H "Content-Type: application/json" \
  -H "x-locus-request-id: <UUID from the 402 response>" \
  -d '{"model":"<string>","messages":"<array>","contents":"<array>","systemInstruction":"<string>","maxOutputTokens":"<number>","temperature":"<number>","topP":"<number>","topK":"<number>","thinking":"<string | boolean | number>","responseMimeType":"<string>","responseJsonSchema":"<object>","stopSequences":"<string[]>"}'
```

### Upload Video File

Upload a video to Gemini Files and wait until it is active. Pass the returned file.uri to chat as a fileData part.

**Estimated cost:** $0.003

**Payment:** x402 `exact`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data` | string | No | Raw base64 video bytes without a data-URI prefix (maximum 24 MB decoded). |
| `source_url` | string | No | HTTPS Amazon S3 video URL (maximum 100 MB). Use this for the LocusFounder upload path; provide either source_url or data. |
| `mime_type` | string | Yes | video/mp4, video/quicktime, or video/webm. |
| `display_name` | string | No | Optional file label, maximum 256 characters. |

```bash
curl -X POST https://gemini.x402.beta.paywithlocus.com/gemini/upload-file \
  -H "Content-Type: application/json" \
  -H "x-locus-request-id: <UUID from the 402 response>" \
  -d '{"data":"<string>","source_url":"<string>","mime_type":"<string>","display_name":"<string>"}'
```