Documentation

ColorsResource

Access via client.colors

get()

Get extracted colors for an image. Colors are extracted automatically on upload.

async def get(image_id: str) -> ColorExtractionResult

Returns: ColorExtractionResult - Status and analysis with dominant colors in RGB, HSL, LAB

extract()

Re-run color extraction with custom settings. Only needed to change n_colors or force a refresh.

async def extract(
    image_id: str,
    *,
    force: bool = False,  # Force re-extraction
    n_colors: int = 16,  # 3-16
) -> ColorExtractionResult

search()

Search images by color properties

async def search(
    *,
    hex_code: Optional[str] = None,  # e.g., "#C4A87C"
    color_name: Optional[str] = None,  # e.g., "walnut", "brass"
    color_family: Optional[str] = None,  # e.g., "earth_tone", "metallic"
    delta_e_threshold: float = 15.0,  # Color tolerance (0-100)
    min_percentage: float = 5.0,  # Minimum color coverage (0-100)
    limit: int = 50,  # 1-200
    offset: int = 0,
) -> ColorSearchResponse

Returns: ColorSearchResponse - Matching images with match scores

Example

# Search by hex color
results = await client.colors.search(
    hex_code="#8B4513",  # Saddle brown
    delta_e_threshold=20.0,  # Allow similar colors
)

# Search by family
earth_images = await client.colors.search(color_family="earth_tone")

search_all()

Auto-paginating async iterator that yields all color search results

async def search_all(
    *,
    hex_code: Optional[str] = None,
    color_name: Optional[str] = None,
    color_family: Optional[str] = None,
    delta_e_threshold: float = 15.0,
    min_percentage: float = 5.0,
    page_size: int = 50,
) -> AsyncIterator[ColorSearchResult]

Yields: ColorSearchResult objects one at a time, automatically paginating through all results

list_families()

List available color families

async def list_families() -> list[ColorFamilyInfo]

Returns families: neutral, earth_tone, warm, cool, metallic, pastel, vibrant

batch_extract()

Re-run color extraction for multiple images (max 1000). Only needed to change settings.

async def batch_extract(
    image_ids: list[str],
    *,
    force: bool = False,
    n_colors: int = 16,
) -> BatchColorExtractionResult

Color Analysis Guide

How to extract and search colors

Color Types

ColorAnalysis, DominantColor, RGB, HSL, LAB