Skip to main content

​
Templates API

The Templates API lets you programmatically render OG image templates. Use it to generate dynamic social images from your templates and include them in posts or use them externally.

​
Render a Template

Render an OG image template with the provided configuration and return the generated image URL. 
POST /v1/templates
This endpoint is also available at the alias: 
POST /v1/media/render-og
Both paths are functionally identical.

​
Headers

HeaderRequiredDescription
Content-TypeYesMust be application/json
soku-api-keyYesYour Soku API key

​
Request Body

FieldTypeRequiredDescription
templateSlugstringYesThe slug identifier of the template to render. You can find this in the template editor in the Soku dashboard.
configobjectNoA key-value object of configuration options for the template. The available keys depend on the specific template. If omitted, the template renders with its default configuration.
aspectRatiostringNoThe aspect ratio for the rendered image. Supported values: "1:1", "4:5", "9:16". If omitted, the template’s default aspect ratio is used.

​
Config Object

The config object varies by template. Each template defines its own set of configurable fields. Common fields for the built-in tweetImage template are shown below as an example:
FieldTypeDescription
titlestringThe main heading text rendered on the image
subtitlestringSecondary text below the title
authorstringAuthor name displayed on the image
avatarstringURL of the author’s avatar image
themestringColor theme for the image (for example, "dark", "light")
The fields available in the config object depend entirely on the template you are rendering. Check your template configuration in the Soku dashboard under Templates for the exact fields and their expected values.

​
Response

FieldTypeDescription
urlstringThe URL of the rendered image. This URL is hosted on Soku’s storage and can be used directly in posts or downloaded.
idstringA unique identifier for the rendered image.
{
  "url": "https://storage.mysoku.io/og/a1b2c3d4-e5f6-7890.png",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Examples

​
Render a tweet image template

curl -X POST https://api.mysoku.io/v1/templates \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "templateSlug": "tweetImage",
    "config": {
      "title": "Ship fast, learn faster.",
      "author": "Soku Team",
      "theme": "dark"
    }
  }'
Response: 
{
  "url": "https://storage.mysoku.io/og/f7e8d9c0-b3c4-d5e6.png",
  "id": "f7e8d9c0-b3c4-d5e6-a7b8-c9d0e1f23456"
}

​
Using the alias endpoint

The same request can be made using the /v1/media/render-og alias: 
curl -X POST https://api.mysoku.io/v1/media/render-og \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "templateSlug": "tweetImage",
    "config": {
      "title": "Consistency beats intensity.",
      "subtitle": "Post every day for 30 days.",
      "author": "Content Creator",
      "theme": "light"
    }
  }'

​
Render and publish in one workflow

Generate an OG image and include it in a post: 
# Step 1: Render the template
IMAGE_URL=$(curl -s -X POST https://api.mysoku.io/v1/templates \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "templateSlug": "tweetImage",
    "config": {
      "title": "New blog post: API Best Practices",
      "author": "Dev Team",
      "theme": "dark"
    }
  }' | jq -r '.url')

# Step 2: Publish a post with the rendered image
curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d "{
    \"post\": {
      \"content\": {
        \"text\": \"New on the blog: API Best Practices for Social Media Automation\",
        \"mediaType\": \"image\",
        \"imageUrls\": [\"$IMAGE_URL\"],
        \"platform\": [\"x\", \"linkedin\", \"facebook\"]
      }
    }
  }"

​
Error Responses

HTTP StatusError CodeDescription
400validation_errorMissing or invalid templateSlug or config fields
401unauthorizedMissing or invalid API key
403forbiddenSubscription is not active
404not_foundThe specified templateSlug does not match any template in your account
429rate_limit_exceededToo many requests. See Rate Limits.
500internal_errorAn error occurred during image rendering
Example error response: 
{
  "error": {
    "type": "api_error",
    "code": "not_found",
    "message": "No template found with slug 'nonExistentTemplate'.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456"
  }
}

​
Next Steps

TopicDescription
Posts APIUse rendered images in post submissions
Media APIUpload other media for use in posts
OG Image TemplatesLearn how to create and configure templates in the dashboard