# Google Gemini — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.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.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://paywithlocus.com/x402/gemini.md)

## Endpoints

### List Models

List the Gemini models available to the configured upstream account and their supported generation methods.

**Estimated cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pageSize` | number | No | Maximum number of models to return per page |
| `pageToken` | string | No | Pagination token from a previous response |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/gemini/models \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 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-3.7-flash', 'gemini-3.6-flash', 'gemini-3.5-flash', 'gemini-3.5-flash-lite', 'gemini-3.1-pro-preview', 'gemini-2.5-pro') |
| `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.paywithlocus.com/api/wrapped/gemini/chat \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Reply with the word OK."}],"maxOutputTokens":8,"temperature":0}'
```

### 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.paywithlocus.com/api/wrapped/gemini/upload-file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAMubW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAAHgAAQAAAQAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAll0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAAHgAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAABAAAAAQAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAAAB4AAAAAAABAAAAAAHRbWRpYQAAACBtZGhkAAAAAAAAAAAAAAAAAAAyAAAABgBVxAAAAAAALWhkbHIAAAAAAAAAAHZpZGUAAAAAAAAAAAAAAABWaWRlb0hhbmRsZXIAAAABfG1pbmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQAAAAx1cmwgAAAAAQAAATxzdGJsAAAAuHN0c2QAAAAAAAAAAQAAAKhhdmMxAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAABAAEABIAAAASAAAAAAAAAABFUxhdmM2Mi4xMS4xMDAgbGlieDI2NAAAAAAAAAAAAAAAGP//AAAALmF2Y0MBQsAK/+EAFmdCwArZHsBEAAADAAQAAAMAyDxImSABAAVoy4PLIAAAABBwYXNwAAAAAQAAAAEAAAAUYnRydAAAAAAAAKxlAAAAAAAAABhzdHRzAAAAAAAAAAEAAAADAAACAAAAABRzdHNzAAAAAAAAAAEAAAABAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAADAAAAAQAAACBzdHN6AAAAAAAAAAAAAAADAAACgwAAAAkAAAAKAAAAFHN0Y28AAAAAAAAAAQAAA14AAABhdWR0YQAAAFltZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAACxpbHN0AAAAJKl0b28AAAAcZGF0YQAAAAEAAAAATGF2ZjYyLjMuMTAwAAAACGZyZWUAAAKebWRhdAAAAnEGBf//bdxF6b3m2Ui3lizYINkj7u94MjY0IC0gY29yZSAxNjUgcjMyMjIgYjM1NjA1YSAtIEguMjY0L01QRUctNCBBVkMgY29kZWMgLSBDb3B5bGVmdCAyMDAzLTIwMjUgLSBodHRwOi8vd3d3LnZpZGVvbGFuLm9yZy94MjY0Lmh0bWwgLSBvcHRpb25zOiBjYWJhYz0wIHJlZj0zIGRlYmxvY2s9MTowOjAgYW5hbHlzZT0weDE6MHgxMTEgbWU9aGV4IHN1Ym1lPTcgcHN5PTEgcHN5X3JkPTEuMDA6MC4wMCBtaXhlZF9yZWY9MSBtZV9yYW5nZT0xNiBjaHJvbWFfbWU9MSB0cmVsbGlzPTEgOHg4ZGN0PTAgY3FtPTAgZGVhZHpvbmU9MjEsMTEgZmFzdF9wc2tpcD0xIGNocm9tYV9xcF9vZmZzZXQ9LTIgdGhyZWFkcz0xIGxvb2thaGVhZF90aHJlYWRzPTEgc2xpY2VkX3RocmVhZHM9MCBucj0wIGRlY2ltYXRlPTEgaW50ZXJsYWNlZD0wIGJsdXJheV9jb21wYXQ9MCBjb25zdHJhaW5lZF9pbnRyYT0wIGJmcmFtZXM9MCB3ZWlnaHRwPTAga2V5aW50PTI1MCBrZXlpbnRfbWluPTI1IHNjZW5lY3V0PTQwIGludHJhX3JlZnJlc2g9MCByY19sb29rYWhlYWQ9NDAgcmM9Y3JmIG1idHJlZT0xIGNyZj0yMy4wIHFjb21wPTAuNjAgcXBtaW49MCBxcG1heD02OSBxcHN0ZXA9NCBpcF9yYXRpbz0xLjQwIGFxPTE6MS4wMACAAAAACmWIhAvyYoAAq84AAAAFQZo4F+oAAAAGQZpUBXqA","mime_type":"video/mp4","display_name":"locus-endpoint-audit.mp4"}'
```

### Embed

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

**Estimated cost:** ~$0.0002

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | No | Embedding model ID: 'gemini-embedding-2' (current), 'gemini-embedding-2-preview', or 'gemini-embedding-001' (default for compatibility) |
| `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.paywithlocus.com/api/wrapped/gemini/embed \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from x402"}'
```

### 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.paywithlocus.com/api/wrapped/gemini/count-tokens \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Hello from the Locus API audit"}]}'
```