Image color temperature adjustment

It estimates the average color’s correlated color temperature, applies the requested warmer or cooler change, and reports normalized red, green, and blue gains. Use the result in a linear-light color pipeline to create a repeatable white-balance adjustment without uploading the image itself. The calculation is deterministic, transparent, and available for $0.002 per API request.

Prepare a representative average RGB value

Start with the arithmetic average of each 8-bit sRGB channel across the pixels you want the correction to represent. Supply those values as avg_r, avg_g, and avg_b on the familiar zero-to-255 scale. A whole-image average works for broadly illuminated photographs, product batches, thumbnails, and automated previews. For an image with a strongly colored subject, however, a neutral-region average may describe the illuminant more faithfully than the entire frame. A red wall or blue ocean can dominate a global average even when the camera white balance is already correct. The calculator does not inspect pixels, identify neutral objects, or distinguish lighting from subject color; it uses exactly the summary you provide. Fully black averages are rejected because they contain no chromaticity from which to estimate temperature. Values outside the 8-bit range and non-finite numbers are also rejected. Keeping the sampling method consistent across a batch is important: comparable averages produce comparable corrections, while changing masks or crop regions between images can make identical lighting appear different to the calculation.

Choose the Kelvin shift and understand the model

Enter shift_kelvin as a relative change, not an absolute destination. A positive value raises the estimated temperature and creates a cooler correction; a negative value lowers it and creates a warmer correction. Shifts from minus 10,000 through plus 10,000 Kelvin are supported, and the resulting target must remain between 1,000 and 40,000 Kelvin. The calculation first linearizes the average sRGB channels, converts them to CIE XYZ chromaticity, and estimates correlated color temperature with McCamy’s cubic approximation. It then evaluates deterministic blackbody RGB curves at the estimated and target temperatures. The ratio between those two white points becomes a set of channel gains, normalized so that green equals one. This is an engineering approximation rather than a spectral measurement. Correlated color temperature is most meaningful near the Planckian locus, so highly saturated averages can only provide a rough estimate. The returned method and temperatures make the assumption visible and let a processing pipeline record exactly how each gain set was produced.

Apply the multipliers without damaging the image

Apply red_multiplier, green_multiplier, and blue_multiplier to linear-light RGB values, not directly to gamma-encoded 8-bit channel numbers. A reliable workflow decodes sRGB to linear light, multiplies each channel by its corresponding gain, handles values above the display range with exposure adjustment or tone mapping, and then encodes the result back to sRGB. Multiplying encoded bytes directly may look plausible for a small shift, but it does not preserve the intended relationship between light and stored values. Green is normalized to one, so the result expresses chromatic balance rather than an overall exposure change. Red or blue may exceed one, and clipping can occur in bright areas; process with floating-point or sufficient bit depth before the final export. Preview the result on representative images before applying it to a large collection, especially when the average came from colorful scenery rather than a neutral reference. The API price is $0.002 per request, while the browser calculator can perform the same deterministic arithmetic locally without transmitting image pixels.