API Documentation

SocImage is a free API for generating social media banners on demand. Send a template index and your content, get back a ready-to-post PNG image.

Endpoints

POST /api/banner
GET  /api/templates

Discover Available Templates

Before generating a banner, you can check which templates exist and which fields each one actually uses. GET /api/templates returns every available template along with a per-field usage flag (required, optional, or unused), so you know exactly what to send for any given index without guessing.

Example response:

[
  {
    "index": 1,
    "fields": {
      "main_image": "optional",
      "headline": "optional",
      "content": "required",
      "brand_name": "optional",
      "brand_identifier": "optional",
      "brand_image": "optional"
    }
  }
]

Generate a Banner

POST /api/banner

• Content-Type: application/json
• Response: image/png

Request Payload

Every template accepts the same fixed set of fields. Use /api/templates to check which fields a specific index actually uses before sending a request.

Field	Type	Required	Description
index	number	No	Which banner template to use (e.g. 1, 2, 89). Returns an error if the index does not exist.
main_image	string (URL)	No	Primary visual used by the banner, treatment depends on the template.
headline	string	No	Optional bold title, used alongside content when a banner needs two distinct pieces of text.
content	string	No	The main text of the banner. See “Text Priority” below.
brand_name	string	No	Name of the writer, author, or brand.
brand_identifier	string	No	Small identity marker, e.g. a domain, @handle, or author credit.
brand_image	string (URL)	No	Avatar, logo, or small brand image.
width	number	No	Output image width in pixels. Defaults to 1080.
height	number	No	Output image height in pixels. Defaults to 1080.

Text Priority: content vs headline

content is always the primary text field.

• If a banner only needs one block of text (a quote, a caption, a single statement), put it in content, not headline.
• Every template treats content as its default, most prominent text when headline is absent.
• headline is optional and only comes into play when a banner needs two distinct pieces of text, a short bold title plus a supporting body.
• In that case, headline acts as the title and content becomes the secondary explanatory text underneath it.
• Sending headline alone without content is not recommended, most templates are designed around content being present, with headline layered on top of it, not the other way around.

Single text example (content only):

{
  "content": "Be so in love with your life that nobody's absence or presence can alter your peace."
}

Two-text example (headline + content together):

{
  "headline": "News at 19",
  "content": "There is a man who changed everything about how we think of peace."
}

Example Request

{
  "index": 0,
  "main_image": "https://images.unsplash.com/photo-1500534623283-312aade485b7?q=80&w=1200&auto=format&fit=crop",
  "content": "Be so in love with your life that nobody's absence or presence can alter your peace.",
  "brand_name": "Ucscode",
  "width": 1080,
  "height": 1080
}

Example cURL

curl -X POST https://socimage.ucscode.com/api/banner \
-H "Content-Type: application/json" \
-d '{
  "index": 0,
  "content": "Be so in love with your life that nobody'\''s absence or presence can alter your peace.",
  "brand_name": "Ucscode"
}' \
--output banner.png

Response

On success, the API returns the generated image directly as binary PNG data with Content-Type: image/png. Save the response body as a .png file, or stream it straight into your posting workflow.

On failure, it returns a JSON error object instead:

{
  "error": "Unknown template index: 42"
}

Choosing a Template

Every available template is listed on the homepage, each tagged with its index number. Check /api/templates to see exactly which fields each template supports before building your request.

You can also preview any template directly, including with custom query overrides for quick testing:

/preview/banner-1?content=Test+content&width=1080&height=1350

Notes

• Fields are optional. A template will only render the fields its layout is designed to use.
• content is the primary text field. Use headline only when a second, distinct block of text is needed.
• If an unknown index is sent, the API returns a 400 error with a JSON message.
• See /api/templates any time to check which fields a template actually supports.