REST API Reference

Technical API Documentation

Reference documentation for generating banners and dynamic images using the Banner.codes API.

Base URL

All requests must use HTTPS.

https://api.banner.codes

Authentication

API key authentication.

Include your API key in the request headers.

x-api-key: YOUR_API_KEY

Endpoint

Generate banner images.

POST/render

Request Parameters

Name	Type	Required	Description
`title`	string	Required	Primary text displayed on the banner.
`subtitle`	string	Optional	Secondary supporting text.
`theme`	"dark" \| "light"	Optional	Visual theme for the generated image.
`width`	number	Optional	Image width in pixels.
`height`	number	Optional	Image height in pixels.
`format`	"png" \| "jpeg"	Optional	Output image format.

Request Examples

cURL

curl -X POST https://api.banner.codes/render \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "title": "Launch Day",
    "subtitle": "Version 2.0 Released",
    "theme": "dark"
  }'

JavaScript

fetch("https://api.banner.codes/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BANNER_API_KEY
  },
  body: JSON.stringify({
    title: "Launch Day",
    subtitle: "Version 2.0 Released",
    theme: "dark"
  })
})

Response

Successful Response

Returns an image file.

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=3600

Error Codes

400Bad Request

Missing or invalid request parameters.

401Unauthorized

Missing API key.

429Rate Limited

Too many requests in a short period.

500Server Error

Unexpected rendering error.

Rate Limits

Free

100/day

Pro

Higher limits

Enterprise

Custom

Best Practices

Environment Variables

Store API keys securely using environment variables.

Cache Responses

Cache generated images when possible to reduce API usage.

Avoid Client Exposure

Never expose private API keys directly in frontend applications.