API Documentation

Generate social media images and videos seamlessly via our all-in-one REST API endpoint.

Authentication

To authenticate requests, you must pass your API key. We support several methods, but we highly recommend sending it via the request body or header.

Method	Example
JSON Body (Recommended)	`"api_key": "YOUR_API_KEY"`
Header	`x-api-key: YOUR_API_KEY`
Header (Bearer)	`Authorization: Bearer YOUR_API_KEY`

Your key: SOCIAL_RUN_ADV_SECRET_2026. Keep this secret. Do not expose it in client-side code.

Parameters

Our endpoint takes a clean JSON payload. Pass these properties at the root level of your request body.

Parameter	Type	Required	Description
`api_key`	String	Required	Your authentication key (if not passing via Header).
`template_id`	String	Required	Template identifier to use (e.g. `"tpl_1"`, `"tpl_2"`).
`format`	String	Required	Define output medium. Exactly: `"image"` or `"video"`.
`main_image` (or `main_video`)	String URL	Required	The full public URL of the core background image/video. Our server will automatically download this file.
`headline`	String	Required	The main headline text you wish to inject into the template.
`logo_url`	String URL	Optional	Custom URL bridging to your brand logo. Will override the template's default logo.
`socialber_url`	String URL	Optional	Custom URL bridging to a social handles graphic for the footer.
`image_height`	Integer	Optional	Overrides canvas height in pixels (e.g., `1080`).
`image_width`	Integer	Optional	Overrides canvas width in pixels (e.g., `1080`).
`background_colour`	String	Optional	Hex override if you want a flat color without an image, e.g. `"#000000"`.
`font_size`	Integer	Optional	Numeric font size override (e.g. `48`). Scales dynamically.
`font_style`	String	Optional	Exact font family name to override typography.

Supported Font Families for font_style:
League Spartan, Hind Siliguri, Baloo Da 2, Noto Serif Bengali, Tiro Bangla, Anek Bangla, Galada, Inter, Outfit, Montserrat, Roboto, Open Sans, Lato, Poppins, Oswald.

Basic JSON for Image

The simplest way to generate an image utilizing only the required properties. It falls back to template dimensions, fonts, and preset icons.

{
  "api_key":     "YOUR_API_KEY",
  "template_id": "tpl_1",
  "format":      "image",
  "main_image":  "https://example.com/stadium.jpg",
  "headline":    "India claims historic victory!"
}

Basic JSON for Video

Swap format to video, and pass a main_video URL.

{
  "api_key":     "YOUR_API_KEY",
  "template_id": "tpl_4",
  "format":      "video",
  "main_video":  "https://example.com/goals.mp4",
  "headline":    "Watch these spectacular highlights"
}

Advanced JSON (All Options)

Utilize everything to completely restyle a template using the optional fields dynamically.

{
  "api_key":           "YOUR_API_KEY",
  "template_id":       "tpl_2",
  "format":            "image",
  "main_image":        "https://example.com/event.png",
  "headline":          "ব্র্যাকিং নিউজ: বাংলায় নতুন খবর",
  "logo_url":          "https://example.com/clients/logo44.png",
  "socialber_url":     "https://example.com/clients/social_footer.png",
  "background_colour": "#0f172a",
  "font_style":        "Tiro Bangla",
  "font_size":         58,
  "image_width":       1080,
  "image_height":      1350
}

n8n Setup

Create automation effortlessly using an HTTP Request node.

1

Add HTTP Request nodeMethod: POST | URL: https://socialrunai.com/api/api.php
2

Set Body formatEnable "Send Body" and choose JSON format.

Configure JSON payloadPass dynamic expressions inside the body.

{
  "api_key":     "SOCIAL_RUN_ADV_SECRET_2026",
  "template_id": "tpl_1",
  "format":      "image",
  "main_image":  "{{ $json.image_url }}",
  "headline":    "{{ $json.article_title }}"
}

4

Success!Retrieve your final image dynamically in the next node via {{ $json.media_url }}.

Make (Integromat) Setup

To integrate via Make.com, utilize the generic "HTTP - Make a request" module.

1

Configure HTTP ModuleURL: https://socialrunai.com/api/api.php | Method: POST
2

Body TypeSelect Raw and set Content type to JSON (application/json).

Request ContentBuild the JSON by mapping scenario variables.

{
  "api_key":     "SOCIAL_RUN_ADV_SECRET_2026",
  "template_id": "tpl_1",
  "format":      "image",
  "main_image":  "{{1.image_url}}",
  "headline":    "{{1.title}}"
}

4

Parse ResponseSet "Parse response" to Yes. You'll instantly get media_url directly mapped for following modules.

Zapier Setup

Utilize the Webhooks by Zapier app to trigger generations.

1

Create ActionChoose app: Webhooks by Zapier | Action Event: Custom Request
2

Configure SetupMethod: POST | URL: https://socialrunai.com/api/api.php

Data (Payload)Copy this JSON structure and inject mapped Zapier data directly into the fields:

{
  "api_key":     "SOCIAL_RUN_ADV_SECRET_2026",
  "template_id": "tpl_2",
  "format":      "image",
  "main_image":  "{{Step1.Background_URL}}",
  "headline":    "{{Step1.Sheet_Headline}}"
}

4

HeadersSet Content-Type : application/json (or the API won't decode the raw body string correctly).

Error Codes

Code	Meaning	Fix/Action
200 success	Graphic rendered instantly	Distribute `media_url` from JSON response globally.
200 queued	Video dispatched to FFmpeg engine	Background processing started. Check server logs momentarily.
400 Bad Request	Missing payload attributes	Make sure `template_id`, `headline`, and `main_image` are sent.
401 Unauthorized	Missing or bad API Key	Include key inside `api_key` property inside JSON Payload.
500 Server Error	Processing Engine failure	Usually Pango/Imagick rendering crashing. Check `debug` in response body.

Live API Tester

🚀 Fast API Ping

API Key

Endpoint

JSON Payload