API Documentation

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

Endpoints

POST /api/card
GET  /api/templates
GET  /api/templates/{id}

Discover Available Templates

Before generating a card, check which templates exist and which fields each one uses. GET /api/templates returns every available template with a description and a per-field usage flag: required, optional, or void.

To retrieve one template specification:

GET /api/templates/17

Generate a Card

POST /api/card
Content-Type: application/json

Successful responses use Content-Type: image/png.

Rate Limit

Image generation through POST /api/card is limited to 50 requests per minute per IP address.

Automation tools may send more requests than expected when a node receives multiple items. For example, passing 20 items into an HTTP request node can result in 20 image-generation requests rather than one.

If you only need one image, reduce the input to one item before calling SocImage. For larger workloads, batch or space requests instead of sending them all at once.

When the limit is exceeded, the API returns HTTP 429 with RATE_LIMIT_EXCEEDED. Use the returned Retry-After value before trying again.

Request Payload

Every template accepts the same fixed field names, while required fields vary by design.

The former width, height, and min_height fields are no longer accepted. Use size and fit_content instead.

Field	Type	Required	Description
`index`	number	Yes	Non-negative integer identifying the template. The request is rejected when it is missing, invalid, or does not exist.
`size`	number	No	Width and minimum height in pixels. Defaults to `1080`.
`fit_content`	boolean	No	When true, removes the minimum height so the PNG fits its content. Defaults to `false`.
`main_image`	string (URL)	Template-dependent	Primary visual used by the card.
`headline`	string	Template-dependent	Optional or required secondary/title text depending on the template.
`content`	string	Yes	Primary card text. Supports restricted inline styling.
`brand_name`	string	Template-dependent	Writer, author, publication, or brand name.
`brand_identifier`	string	Template-dependent	Domain, handle, author credit, or other identity marker.
`brand_image`	string (URL)	Template-dependent	Avatar or logo.
`meta`	object	No	Template-specific display settings.
`format`	string	No	Output format: `png`, `jpg`, `jpeg`, `webp`, or `avif`. Defaults to `png`. Non-PNG formats use Sharp.
`compress`	boolean	No	When true, processes the output through Sharp. PNG output uses palette compression. Defaults to `false`.
`quality`	number	No	Sharp output quality from `1` to `100`. Defaults to `90` for PNG and `82` for other formats.
`effort`	number	No	Sharp encoder effort from `1` to `9`. Defaults to `6`.

Text Priority: `content` vs `headline`

content is the primary text field and is required by every current template.

For a single quote, statement, or caption, use content.
headline is only used when the selected template supports a second text block.
A template may mark headline as required, optional, or void.
Check /api/templates instead of assuming a field is supported.

Inline Text Styling

content and any supported headline can contain a restricted [style ...]...[/style] block.

Focus on [style color=yellow bold underline]progress[/style], not perfection.

Supported style flags:

color={colorname}
bold
light
underline

If both bold and light are supplied, the first one written in the style block takes priority.

Supported colors:

red, orange, amber, yellow, lime, green, emerald, teal, cyan, blue, indigo, violet, purple, pink, rose, white, black, gray, slate

Color values may be unquoted, double-quoted, or single-quoted:

[style color=yellow]progress[/style]

[style color="yellow"]progress[/style]

[style color='yellow']progress[/style]

Styles can be combined without introducing extra blocks:

[style color=cyan light underline]subtle emphasis[/style]

[style color=red bold]important warning[/style]

Can style blocks be nested?

No. Nested [style] blocks are not currently supported. Combine all desired styles in one block.

Use:

[style color=yellow bold underline]progress[/style]

Do not rely on:

[style bold][style color=yellow]progress[/style][/style]

The renderer only accepts known style flags and whitelisted color names. Normal text and arbitrary HTML are escaped rather than rendered.

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"
}

Example cURL

curl -X POST https://socimage.ucscode.com/api/card \
-H "Content-Type: application/json" \
-d '{
  "index": 0,
  "content": "Focus on [style color=blue bold]progress[/style], not perfection."
}' \
--output card.png

Response

On success, the API returns binary image data with the matching Content-Type. The default is an unprocessed PNG; requests using format may instead return JPEG, WebP, or AVIF. Save the response using the corresponding extension or pass the binary directly into an automation or publishing workflow.

If the template index does not exist, the API returns a JSON error. Missing required fields return 400 before rendering.

{
  "error": "Missing required fields",
  "code": "MISSING_REQUIRED_FIELDS",
  "missing_fields": ["content"]
}

Previewing Templates

Every available template is listed on the homepage. Select a sample image to open its larger PNG preview, or choose Edit to generate a customized preview through POST /api/card.

For exact field requirements, use /api/templates or /api/templates/{id}.