Complementary Color API: The Complete Guide to Color Harmonies

Need to find colors that work well together? This guide covers everything you need to know about generating color harmonies programmatically via API, including complementary, analogous, triadic schemes and implementation examples in multiple languages.

What are Complementary Colors?

Complementary colors are pairs of colors that, when combined, create a strong visual contrast. They sit opposite each other on the color wheel and are the foundation of effective color design.

For example, the complementary color of blue (#0000ff) is orange (#ff8000), and the complementary of red (#ff0000) is cyan (#00ffff).

Color Harmony Types

There are several types of color harmonies you can generate:

Complementary

Two colors opposite on the color wheel (180 degrees apart). High contrast, bold combinations.

Analogous

Three colors adjacent on the color wheel (30 degrees apart). Harmonious, nature-inspired combinations.

Triadic

Three colors evenly spaced (120 degrees apart). Balanced, vibrant combinations.

Split-Complementary

Base color plus two colors adjacent to its complement. High contrast but less tension than complementary.

Using the Complementary Color API

TinyFn provides a simple endpoint to find color harmonies:

GET https://api.tinyfn.io/v1/color/complementary?color=%233498db&harmony=complementary
Headers: X-API-Key: your-api-key

{
  "input": "#3498db",
  "harmony": "complementary",
  "colors": [
    "#3498db",
    "#db8834"
  ],
  "description": "Complementary colors are opposite on the color wheel"
}

Parameters

Code Examples

JavaScript / Node.js

// Get complementary color
const response = await fetch(
  'https://api.tinyfn.io/v1/color/complementary?color=%233498db&harmony=complementary',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { colors } = await response.json();
console.log(colors); // ['#3498db', '#db8834']

// Get triadic colors
const triadicResponse = await fetch(
  'https://api.tinyfn.io/v1/color/complementary?color=%233498db&harmony=triadic',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const triadic = await triadicResponse.json();
console.log(triadic.colors); // ['#3498db', '#98db34', '#db3498']

Python

import requests

# Get complementary color
response = requests.get(
    'https://api.tinyfn.io/v1/color/complementary',
    params={'color': '#3498db', 'harmony': 'complementary'},
    headers={'X-API-Key': 'your-api-key'}
)
colors = response.json()['colors']
print(colors)  # ['#3498db', '#db8834']

# Get analogous colors
response = requests.get(
    'https://api.tinyfn.io/v1/color/complementary',
    params={'color': '#3498db', 'harmony': 'analogous'},
    headers={'X-API-Key': 'your-api-key'}
)
analogous = response.json()['colors']
print(analogous)  # ['#3498db', '#3434db', '#34db98']

cURL

# Get complementary color
curl "https://api.tinyfn.io/v1/color/complementary?color=%233498db&harmony=complementary" \
  -H "X-API-Key: your-api-key"

# Get triadic colors
curl "https://api.tinyfn.io/v1/color/complementary?color=%233498db&harmony=triadic" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Brand Identity: Build complete color palettes from a single brand color
• UI Design: Find accent colors that work with primary colors
• Data Visualization: Generate distinct but harmonious chart colors
• Theme Generation: Create cohesive color themes automatically
• Accessibility: Find high-contrast complementary pairs

Best Practices

1. Use analogous for subtle designs: Low contrast, soothing palettes
2. Use complementary for CTAs: High contrast draws attention
3. Balance saturation: Tone down one color in complementary pairs
4. Test in context: Colors look different based on surrounding colors

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-color": {
      "url": "https://api.tinyfn.io/mcp/color/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all color tools available via MCP in our Color MCP Tools for AI Agents guide.