# OpenAI — 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.

> AI models — chat completions, embeddings, image generation/editing, text-to-speech, and content moderation.

**Category:** AI / LLM | **Website:** [openai.com](https://openai.com) | **Docs:** [platform.openai.com/docs](https://platform.openai.com/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/openai/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Chat Completions

Generate text with GPT and o-series models. Supports text, vision (images via URL or base64), structured output (JSON mode), and function calling.

**Estimated cost:** Model-dependent (~$0.001–$0.20)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Model ID (e.g. 'gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4.1-nano', 'o3', 'o4-mini', 'gpt-5', 'gpt-5-mini') |
| `messages` | array | Yes | Conversation messages. Each: { role: "system"\|"user"\|"assistant", content: "text" } or multimodal: { role: "user", content: [{ type: "text", text: "..." }, { type: "image_url", image_url: { url: "..." } }] } |
| `temperature` | number | No | Sampling temperature (0.0–2.0, default 1.0). Not supported for o-series reasoning models. |
| `top_p` | number | No | Nucleus sampling threshold (0.0–1.0) |
| `max_tokens` | number | No | Maximum output tokens. Use max_completion_tokens for o-series models. |
| `max_completion_tokens` | number | No | Maximum completion tokens (preferred for o-series reasoning models) |
| `response_format` | object | No | Response format. { type: "json_object" } for JSON mode, or { type: "json_schema", json_schema: { ... } } for structured output. |
| `stop` | string \| string[] | No | Stop sequences (up to 4) |
| `frequency_penalty` | number | No | Frequency penalty (-2.0 to 2.0, default 0) |
| `presence_penalty` | number | No | Presence penalty (-2.0 to 2.0, default 0) |
| `n` | number | No | Number of completions to generate (default 1) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/openai/chat \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","messages":"<array>","temperature":"<number>","top_p":"<number>","max_tokens":"<number>","max_completion_tokens":"<number>","response_format":"<object>","stop":"<string | string[]>","frequency_penalty":"<number>","presence_penalty":"<number>","n":"<number>"}'
```

### Embeddings

Generate vector embeddings for semantic search, clustering, and classification.

**Estimated cost:** ~$0.0001–$0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | Embedding model ID (e.g. 'text-embedding-3-small', 'text-embedding-3-large', 'text-embedding-ada-002') |
| `input` | string \| string[] | Yes | Text to embed. Can be a single string or array of strings. |
| `encoding_format` | string | No | Encoding format: 'float' (default) or 'base64' |
| `dimensions` | number | No | Output vector dimensions (only for text-embedding-3-* models) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/openai/embed \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","input":"<string | string[]>","encoding_format":"<string>","dimensions":"<number>"}'
```

### Image Generation

Generate images from text prompts using GPT Image models.

**Estimated cost:** $0.005–$0.17 per image

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `model` | string | No | Image model ID (e.g. 'gpt-image-1', 'gpt-image-1-mini'). Default: 'gpt-image-1' |
| `n` | number | No | Number of images to generate (default 1) |
| `size` | string | No | Image size: '1024x1024' (default), '1024x1536', '1536x1024', 'auto' |
| `quality` | string | No | Image quality: 'low', 'medium' (default), 'high' |
| `response_format` | string | No | Response format: 'url' (default) or 'b64_json' |
| `background` | string | No | Background: 'auto' (default), 'transparent', 'opaque' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/openai/image-generate \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"<string>","model":"<string>","n":"<number>","size":"<string>","quality":"<string>","response_format":"<string>","background":"<string>"}'
```

### Text-to-Speech

Convert text to natural-sounding speech audio.

**Estimated cost:** ~$0.015 per 1K chars

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | Yes | TTS model ID: 'tts-1', 'tts-1-hd', 'gpt-4o-mini-tts' |
| `input` | string | Yes | Text to convert to speech (max 4096 characters) |
| `voice` | string | Yes | Voice: 'alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer' |
| `response_format` | string | No | Audio format: 'mp3' (default), 'opus', 'aac', 'flac', 'wav', 'pcm' |
| `speed` | number | No | Speed (0.25–4.0, default 1.0) |
| `instructions` | string | No | Instructions for the TTS model on tone, style, etc. (gpt-4o-mini-tts only) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/openai/tts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<string>","input":"<string>","voice":"<string>","response_format":"<string>","speed":"<number>","instructions":"<string>"}'
```

### Moderation

Classify text for harmful content (harassment, hate, self-harm, sexual, violence). Free from OpenAI, nominal Locus fee.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `input` | string \| string[] | Yes | Text to classify. Can be a single string or array of strings. |
| `model` | string | No | Moderation model: 'omni-moderation-latest' (default), 'text-moderation-latest' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/openai/moderate \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"<string | string[]>","model":"<string>"}'
```