Pixel Harmony API Docs

Overview

Pixel Harmony extracts color palettes from images and PDFs using AI. Each color gets a semantic role (primary, background, accent, etc.), WCAG contrast scores, and ready-to-paste CSS/SCSS/JS exports.

Base URL: https://pixelharmony.app · Version: v1

Note: All API requests must be authenticated. The web app at / is free to use interactively.

Authentication

Pass your API key in the Authorization header on every request.

Authorization: Bearer ph_your_api_key_here

API keys start with ph_. Keep yours secret — treat it like a password.

Example with curl

curl -X POST https://pixelharmony.app/api/analyze-image \
  -H "Authorization: Bearer ph_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "<base64-encoded-image>",
    "mediaType": "image/png",
    "brandName": "Acme Corp"
  }'

Errors

Status	Meaning
401	Missing or malformed Authorization header
403	Invalid or revoked API key
400	Bad request — missing required field
500	Claude could not parse colors from the input

Error responses always include an error string field.

{ "error": "Missing or invalid Authorization header. Use: Bearer <api_key>" }

POST /api/analyze-image

Extracts 5–7 dominant colors from an image. Assigns each a semantic role and returns WCAG contrast scores plus CSS/SCSS/JS export code.

Request body

Field	Type	Required	Description
base64	string	Yes	Base64-encoded image data (no data URL prefix)
mediaType	string	No	MIME type — default `image/jpeg`. Accepts `image/png`, `image/gif`, `image/webp`
brandName	string	No	Used to name variables in exported code (e.g. `acme_corp`)

Example response

{
  "colors": [
    {
      "hex": "#1A3A5C",
      "name": "Deep Navy",
      "usage": "primary",
      "wcag": {
        "vs_white": 10.54,
        "vs_white_level": "AAA",
        "vs_black": 1.99,
        "vs_black_level": "Fail"
      }
    },
    ...
  ],
  "exports": {
    "css": ":root {\n  --primary: #1A3A5C;\n  ...\n}",
    "scss": "$primary: #1A3A5C;\n...",
    "js": "export const acme_corpColors = { \"primary\": \"#1A3A5C\", ... };"
  }
}

POST /api/analyze-pdf

Extracts brand colors from a PDF document (brand guides, decks, style docs). Returns the same structure as /api/analyze-image.

Request body

Field	Type	Required	Description
base64	string	Yes	Base64-encoded PDF data
brandName	string	No	Used to name export variables

GET /api/status

Health check. No authentication required.

{ "status": "ok", "version": "1.0.0" }

Color Object

Every color in the colors array has these fields:

Field	Type	Description
hex	string	Hex color value e.g. `#1A3A5C`
name	string	Descriptive name e.g. `Deep Navy`
usage	string	Semantic role: `primary`, `secondary`, `accent`, `background`, `text`, `surface`, `border`
wcag	object	WCAG contrast scores (see below)

WCAG Scores

Each color includes contrast ratios against white and black, with the WCAG 2.1 level.

Field	Description
vs_white	Contrast ratio against #FFFFFF
vs_white_level	`AAA` (≥7), `AA` (≥4.5), `AA Large` (≥3), `Fail`
vs_black	Contrast ratio against #000000
vs_black_level	Same scale

Exports

The exports object contains ready-to-use code in three formats:

Key	Format	Use case
css	CSS custom properties	Paste into any stylesheet
scss	SCSS variables	Sass/SCSS projects
js	ES module export	React, Vue, Node.js design tokens