# Color Palette API
> Extract the dominant colour palette from any image. Pass an image URL (we fetch it) or a base64 image and get back its main colours — each as a hex code, RGB triplet and the percentage of the image it covers — plus the single dominant colour and the overall average colour. Choose how many colours to return (1 to 16). The image is decoded and downscaled locally and the colours are quantised on the fly; nothing is stored and there is no third-party service. Supports PNG, JPEG, BMP, TIFF and GIF. Live. 2 endpoints. Built for theming and design tools, auto-generating UI colours from artwork or product photos, brand-colour extraction, and image tagging. Distinct from a single-colour converter or an image resize/info service. No upstream key.

## 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/palette-api/..."
```

## Pricing
- **Free** (Free) — 1,650 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 35,000 calls/Mo, 8 req/s
- **Pro** ($28/Mo) — 198,000 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 1,000,000 calls/Mo, 50 req/s

## Endpoints

### Palette

#### `GET /v1/palette` — Extract color palette from an image

**Parameters:**
- `image` (query, required, string) — Base64 image (data-URI or raw) — or use url Example: `iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAKUlEQVR4AYXBsREAMAwCsYfL/iuTFldICoSicJjBDGZ4IrQgmhnMYIYP/XMFEBL0pMsAAAAASUVORK5CYII=`
- `url` (query, optional, string) — Image URL to fetch instead of base64
- `count` (query, optional, string) — Number of colours (1-16, default 6)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/palette-api/v1/palette?image=iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAKUlEQVR4AYXBsREAMAwCsYfL%2FiuTFldICoSicJjBDGZ4IrQgmhnMYIYP%2FXMFEBL0pMsAAAAASUVORK5CYII%3D"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "width": 8,
        "height": 8,
        "average": {
            "hex": "#808040",
            "rgb": {
                "b": 64,
                "g": 128,
                "r": 128
            }
        },
        "palette": [
            {
                "hex": "#ff0000",
                "rgb": {
                    "b": 0,
                    "g": 0,
                    "r": 255
                },
                "percentage": 25
            },
            {
                "hex": "#00ff00",
                "rgb": {
                    "b": 0,
                    "g": 255,
                    "r": 0
                },
                "percentage": 25
            },
            {
                "hex": "#0000ff",
                "rgb": {
                    "b": 255,
                    "g": 0,
                    "r": 0
                },
                "percentage": 25
            },
            {
                "hex": "#ffff00",
                "rgb": {
                    "b": 0,
                    "g": 255,
                    "r": 255
                },
                "percentage": 25
            }
        ],
        "dominant": {
            "hex": "#ff0000",
            "rgb": {
                "b": 0,
                "g": 0,
                "r": 255
            },
            "percentage": 25
        },
        "pixels_sampled": 64
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:03.271Z",
        "request_
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/palette-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "Color Palette API",
        "note": "Extract the dominant colour palette from an image. Pass ?url= an image URL or ?image= a base64 image, with optional ?count=6 (1-16). Returns the palette (hex, RGB, coverage %), the dominant colour and the average colour. Supports PNG, JPEG, BMP, TIFF, GIF. Distinct from color-api (single-colour conversion). Live, nothing stored.",
        "source": "Local extraction (Jimp quantization) — no third-party service, no key",
        "endpoints": 2
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:03.387Z",
        "request_id": "3683ee35-40ee-46f7-b039-f53bdeb52ffa"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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