# Placeholder API
> A fast, fully-local SVG generator for mockups and UIs: placeholder images (a sized rectangle with centered text and automatic contrast), initials avatars (with a deterministic colour derived from the name, in a circle or square), and identicon-style symmetric patterns generated deterministically from any seed. Every endpoint returns the JSON envelope or, with raw=1, the raw SVG so the URL can be used directly as an image source. Pure server-side compute, no third-party upstream, so responses are instant and always available. Ideal for prototypes, dashboards, user avatars, empty states and design systems.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/placeholder-api/..."
```

## Pricing
- **Free** (Free) — 22,000 calls/Mo, 2 req/s
- **Basic** ($3/Mo) — 330,000 calls/Mo, 12 req/s
- **Pro** ($9/Mo) — 2,100,000 calls/Mo, 40 req/s
- **Mega** ($26/Mo) — 11,000,000 calls/Mo, 150 req/s

## Endpoints

### Placeholder

#### `GET /v1/avatar` — Initials avatar (SVG)

**Parameters:**
- `name` (query, required, string) — Name for initials + colour Example: `Ada Lovelace`
- `size` (query, optional, string) — Size 16-1024 (default 128) Example: `128`
- `rounded` (query, optional, string) — circle (true) or square Example: `true`
- `bg` (query, optional, string) — Background hex (deterministic if omitted)
- `raw` (query, optional, string) — Return raw SVG image

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/placeholder-api/v1/avatar?name=Ada+Lovelace&size=128&rounded=true"
```

**Response:**
```json
{
    "data": {
        "bg": "#0891b2",
        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"128\" height=\"128\" viewBox=\"0 0 128 128\"><circle cx=\"64\" cy=\"64\" r=\"64\" fill=\"#0891b2\"/><text x=\"50%\" y=\"50%\" dy=\".35em\" fill=\"#ffffff\" font-family=\"Arial,Helvetica,sans-serif\" font-size=\"51\" font-weight=\"600\" text-anchor=\"middle\">AL</text></svg>",
        "name": "Ada Lovelace",
        "size": 128,
        "color": "#ffffff",
        "format": "svg",
        "rounded": true,
        "initials": "AL"
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.027Z",
        "request_id": "3e9ae28c-5a56-4ac3-bdbf-e88ff9820ef6"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/image` — Placeholder image (SVG)

**Parameters:**
- `width` (query, optional, string) — Width 1-4000 (default 300) Example: `300`
- `height` (query, optional, string) — Height 1-4000 Example: `200`
- `text` (query, optional, string) — Centered text Example: `Hello`
- `bg` (query, optional, string) — Background hex Example: `cccccc`
- `color` (query, optional, string) — Text hex (auto-contrast if omitted)
- `raw` (query, optional, string) — Return raw SVG image

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/placeholder-api/v1/image?width=300&height=200&text=Hello&bg=cccccc"
```

**Response:**
```json
{
    "data": {
        "bg": "#cccccc",
        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"300\" height=\"200\" viewBox=\"0 0 300 200\"><rect width=\"300\" height=\"200\" fill=\"#cccccc\"/><text x=\"50%\" y=\"50%\" dy=\".35em\" fill=\"#333333\" font-family=\"Arial,Helvetica,sans-serif\" font-size=\"40\" font-weight=\"bold\" text-anchor=\"middle\">Hello</text></svg>",
        "text": "Hello",
        "color": "#333333",
        "width": 300,
        "format": "svg",
        "height": 200
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.102Z",
        "request_id": "0b0ce810-39fc-48b2-a8e5-8d620f7088d8"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/pattern` — Identicon pattern (SVG)

**Parameters:**
- `seed` (query, required, string) — Seed (e.g. email/username) Example: `user@example.com`
- `size` (query, optional, string) — Size 32-1024 (default 240) Example: `240`
- `grid` (query, optional, string) — Grid 3-8 (default 5) Example: `5`
- `raw` (query, optional, string) — Return raw SVG image

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/placeholder-api/v1/pattern?seed=user%40example.com&size=240&grid=5"
```

**Response:**
```json
{
    "data": {
        "bg": "#f0f0f0",
        "fg": "#4f46e5",
        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"240\" height=\"240\" viewBox=\"0 0 240 240\"><rect width=\"240\" height=\"240\" fill=\"#f0f0f0\"/><rect x=\"0\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"192\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"0\" y=\"144\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"192\" y=\"144\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"48\" y=\"0\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"144\" y=\"0\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"48\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"144\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"48\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"96\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"96\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"192\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/><rect x=\"96\" y=\"192\" width=\"48\" height=\"48\" fill=\"#4f46e5\"/></svg>",
        "grid": 5,
        "seed": "user@example.com",
        "size": 240,
        "format": "svg"
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.173Z",
        "request_id": "6f4efdf1-1be1-4ade-a053-9a54cbe9e4c0"
    },
    "status": "ok",
    "message": "OK",
    "success
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/placeholder-api
OpenAPI spec: https://www.oanor.com/api/placeholder-api/openapi.json