API Parameters

Complete reference for all available parameters and configuration options

Endpoint

GET /api/image

All parameters are passed as URL query parameters. The API returns a 302 redirect to the image URL.

Required Parameters

`query`

string

Required

The search query to find relevant images. Can be a single word or multiple words describing the desired image.

Examples:

query=mountains

query=coffee%20cup (URL encoded)

query=sunset%20beach

💡 Tip: Use descriptive queries for better results. Multi-word queries should be URL encoded.

Optional Parameters

`provider`

string

Optional

Image provider source. Use ai for AI-generated images or stock photo providers.

Options:

provider=ai (AI-generated)

provider=unsplash (Default)

provider=pexels

provider=pixabay

✨ AI Generation: Requires authentication and uses quota. See Authentication for details.

`style`

string

AI Only

Visual style for AI-generated images. Only applicable when provider=ai.

Styles:

photo

Ultra-realistic photographic style (Default)

minimal

Clean, simple designs with neutral backgrounds

dark

Optimized for dark mode interfaces

illustration

Artistic illustrations and creative designs

Example:

/api/image/800x600-modern-office?provider=ai&style=minimal

`variation`

number

AI Only

Generate a variation of the same image concept. Variations are deterministic - same number always produces the same result.

Range: 1-10

Quota: Free if base exists

Example:

/api/image/800x600-sunset?provider=ai&style=photo&variation=1

`alt`

number

AI Only

Get alternative images for the same query from public cache. Saves quota by reusing existing public generations.

Range: 1-10

Quota: Free if public exists

Example:

/api/image/800x600-headshot?provider=ai&style=photo&alt=2

`visibility`

string

AI Only

Whether the generated image can be shared publicly or kept private to your account.

Options:

private (Default)

public (Shareable)

💡 Tip: Public images can be reused by others via alternatives, helping everyone save quota.

`width`

number

Optional

Desired image width in pixels.

Range: 100 - 4000

Default: 1920

Examples:

width=800

width=1920

width=400

width=3840

`height`

number

Optional

Desired image height in pixels.

Range: 100 - 4000

Default: 1080

Common Aspect Ratios:

width=1920&height=1080 (16:9 - Full HD)

width=1080&height=1080 (1:1 - Square)

width=1080&height=1350 (4:5 - Instagram Portrait)

`api_key`

string

Optional

Your API key for authenticated requests. Required for higher rate limits and premium features.

Format:

pk_live_ or pk_test_ followed by 32+ random characters

Usage:

?api_key=pk_live_YOUR_KEY_HERE (Query parameter)

X-API-Key: pk_live_YOUR_KEY_HERE (Header)

🔒 Security: Never expose your live API keys in client-side code. Use environment variables and server-side requests.

Learn more about authentication →

Response Format

The API returns a 302 redirect to the actual image URL. You can use this in several ways:

HTML Image Tag

<img src="/api/image?query=nature&width=800" alt="Nature" />

The browser automatically follows the redirect and displays the image.

Get Redirect URL

fetch('/api/image?query=nature', { redirect: 'manual' })
  .then(res => res.headers.get('Location'))

Use redirect: 'manual' to get the actual image URL without following the redirect.

Response Headers

Header	Description	Example
`Location`	The actual image URL (on 302 redirect)	`https://images.unsplash.com/...`
`X-Cache`	Whether the result was served from cache	`HIT` or `MISS`
`X-Image-Source`	Which provider served the image	`unsplash`, `pexels`, or `pixabay`
`X-RateLimit-Limit`	Your total rate limit	`1000`
`X-RateLimit-Remaining`	Requests remaining in current window	`987`
`X-RateLimit-Reset`	When rate limit resets (ISO timestamp)	`2025-02-09T12:00:00Z`
`X-Response-Time`	Server processing time	`45ms`

✨ Try AI Generation →

Interactive playground to test all AI styles and features

Response Codes →

Learn about success responses and error handling

Rate Limits →

Understand rate limiting tiers and AI quotas

On This Page