# Google Gemini — Wrapped API

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

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/gemini/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

> Also available via public x402 on Base (no account needed): [x402/gemini.md](https://beta.paywithlocus.com/x402/gemini.md)

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

| 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 | No | 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://api.beta.paywithlocus.com/api/wrapped/gemini/chat \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -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

| 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://api.beta.paywithlocus.com/api/wrapped/gemini/upload-file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"<string>","source_url":"<string>","mime_type":"<string>","display_name":"<string>"}'
```

### Embed

Generate text embeddings for semantic search, clustering, classification, and retrieval. 3072-dimensional vectors.

**Estimated cost:** ~$0.0002

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | Yes | Text to embed (max 2048 tokens) |
| `taskType` | string | No | Embedding task type: 'SEMANTIC_SIMILARITY', 'CLASSIFICATION', 'CLUSTERING', 'RETRIEVAL_DOCUMENT', 'RETRIEVAL_QUERY', 'CODE_RETRIEVAL_QUERY', 'QUESTION_ANSWERING', 'FACT_VERIFICATION' |
| `outputDimensionality` | number | No | Output vector size: 128, 256, 512, 768, 1536, or 3072 (default 3072) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/gemini/embed \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<string>","taskType":"<string>","outputDimensionality":"<number>"}'
```

### Count Tokens

Count tokens for content before making a generation call. Useful for cost estimation.

**Estimated cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Model ID to count tokens for |
| `messages` | array | No | Messages array (same format as chat endpoint). Use this OR contents. |
| `contents` | array | No | Raw Gemini contents array. Use this OR messages. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/gemini/count-tokens \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","contents":"<array>"}'
```