← Back to Generator

Gradient Generator API

REST API endpoint for generating gradient images as PNG files

Endpoint

GET /api/gradient

Generates a gradient image based on the provided query parameters and returns it as a PNG file.

Parameters

All parameters are passed as query parameters in the URL.

Required Parameters

colorsREQUIRED
Comma-separated list of hex colors without the # symbol.
  • Format: ff0000,00ff00,0000ff
  • Minimum: 2 colors
  • Maximum: 10 colors

Optional Parameters

widthOPTIONAL
Image width in pixels (default: 1920)
  • Range: 1-8000
heightOPTIONAL
Image height in pixels (default: 1080)
  • Range: 1-8000
typeOPTIONAL
Gradient type (default: linear)
  • Options: linear, radial, conic
positionsOPTIONAL
Comma-separated list of color stop positions (0-100)
  • Must match the number of colors
  • Example: 0,50,100
  • If omitted, colors are evenly distributed
angleOPTIONAL
Gradient angle in degrees (default: 90)
  • Only applies to linear gradients
  • Example: 45 for diagonal, 180 for vertical
centerXOPTIONAL
Horizontal center position as percentage (default: 50)
  • Range: 0-100
  • Applies to radial and conic gradients
centerYOPTIONAL
Vertical center position as percentage (default: 50)
  • Range: 0-100
  • Applies to radial and conic gradients
startAngleOPTIONAL
Starting angle in degrees (default: 0)
  • Only applies to conic gradients

Response

Success (200 OK)

  • Content-Type: image/png
  • Body: PNG image binary data
  • Cache-Control: public, max-age=31536000, immutable

Error (400 Bad Request)

JSON response with error details when parameters are invalid:

{"error": "Error message here"}

Error (500 Internal Server Error)

JSON response for unexpected errors:

{ "error": "Internal server error", "message": "Detailed error message" }

Examples

Basic Linear Gradient

A 1920x1080 diagonal gradient from red to green to blue at 45 degrees.

/api/gradient?width=1920&height=1080&type=linear&angle=45&colors=ff0000,00ff00,0000ff
Try it

Radial Gradient

An 800x800 radial gradient centered in the middle, transitioning from white to magenta to black.

/api/gradient?width=800&height=800&type=radial¢erX=50¢erY=50&colors=ffffff,ff00ff,000000
Try it

Conic Gradient (Rainbow)

A 600x600 rainbow conic gradient with seven colors.

/api/gradient?width=600&height=600&type=conic&colors=ff0000,ffff00,00ff00,00ffff,0000ff,ff00ff,ff0000
Try it

Custom Color Positions

A linear gradient where the second color appears at 25% instead of the default 50%.

/api/gradient?width=1920&height=1080&type=linear&angle=90&colors=ff6b6b,feca57,ee5a6f&positions=0,25,100
Try it

Sunset Gradient

A diagonal purple gradient suitable for backgrounds.

/api/gradient?width=1920&height=1080&type=linear&angle=135&colors=667eea,764ba2
Try it

Usage in HTML

You can use the API directly in HTML img tags or CSS backgrounds:

As an Image

<img src="/api/gradient?width=1920&height=1080&type=linear&angle=45&colors=ff0000,0000ff" alt="Gradient">

As a Background Image

<div style="background-image: url('/api/gradient?width=1920&height=1080&type=radial&colors=667eea,764ba2');"> Content here </div>

Error Cases