Grayscale Conversion API: Convert Colors to Grayscale

Need to convert colors to grayscale for accessibility testing, print design, or visual effects? This guide covers the Grayscale Conversion API, which offers multiple conversion methods for accurate perceptual results.

Grayscale Conversion Methods

There are several methods to convert a color to grayscale, each with different characteristics:

• Luminosity (Recommended): Uses perceptual weights: 0.2126R + 0.7152G + 0.0722B
• Average: Simple average: (R + G + B) / 3
• Lightness: Uses min/max: (max(R,G,B) + min(R,G,B)) / 2
• Desaturate: Sets HSL saturation to 0

Method Comparison

The luminosity method is generally preferred because it accounts for human perception - we perceive green as brighter than red, and red as brighter than blue, even at the same RGB values.

Using the Grayscale API

TinyFn provides a flexible grayscale conversion endpoint:

GET https://api.tinyfn.io/v1/color/grayscale
Headers: X-API-Key: your-api-key

{
  "original": {
    "hex": "#3498db",
    "rgb": { "r": 52, "g": 152, "b": 219 }
  },
  "grayscale": {
    "hex": "#8c8c8c",
    "rgb": { "r": 140, "g": 140, "b": 140 },
    "value": 140
  },
  "method": "luminosity"
}

Parameters

Code Examples

JavaScript / Node.js

// Convert to grayscale using luminosity
const response = await fetch(
  'https://api.tinyfn.io/v1/color/grayscale?' + new URLSearchParams({
    color: '#e74c3c',
    method: 'luminosity'
  }),
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const result = await response.json();
console.log(result.grayscale.hex); // "#7a7a7a"
console.log(result.grayscale.value); // 122 (brightness value 0-255)

Python

import requests

# Compare different methods
colors = ['#ff0000', '#00ff00', '#0000ff']
for color in colors:
    for method in ['luminosity', 'average']:
        response = requests.get(
            'https://api.tinyfn.io/v1/color/grayscale',
            params={'color': color, 'method': method},
            headers={'X-API-Key': 'your-api-key'}
        )
        result = response.json()
        print(f"{color} ({method}): {result['grayscale']['hex']}")

cURL

curl "https://api.tinyfn.io/v1/color/grayscale?color=%233498db&method=luminosity" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Accessibility Testing: Check if designs work in grayscale
• Print Design: Preview colors for black-and-white printing
• Disabled States: Create grayscale versions for disabled UI
• Image Processing: Convert image colors to grayscale
• Contrast Analysis: Compare perceived brightness of colors

Best Practices

1. Use luminosity: For perceptually accurate results, use the luminosity method
2. Test accessibility: Grayscale conversion helps identify contrast issues
3. Don't rely on color alone: If grayscale versions are indistinguishable, add other visual cues
4. Consider context: Different methods may work better for specific applications

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.