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.

Authentication

This endpoint uses API key authentication. Include your API key in the soku-api-key header. An active Soku subscription (trialing or active) is required.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`soku-api-key`	Yes	Your Soku API key

Rate Limit

20 requests per 60 seconds, in addition to the global tier limit. See Rate Limits.

Request Body

Field	Type	Required	Description
`templateSlug`	string	Yes	The slug identifier of the template to render. You can find this in the template editor in the Soku dashboard.
`config`	object	No	A 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.
`aspectRatio`	string	No	The 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:

Field	Type	Description
`title`	string	The main heading text rendered on the image
`subtitle`	string	Secondary text below the title
`author`	string	Author name displayed on the image
`avatar`	string	URL of the author’s avatar image
`theme`	string	Color 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

Field	Type	Description
`url`	string	The URL of the rendered image. This URL is hosted on Soku’s storage and can be used directly in posts or downloaded.
`id`	string	A 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"
}

Render with a custom aspect ratio

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": "Vertical story format",
      "author": "Content Team",
      "theme": "light"
    },
    "aspectRatio": "9:16"
  }'

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 Status	Error Code	Description
400	`validation_error`	Missing or invalid `templateSlug` or `config` fields
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	Subscription is not active
404	`not_found`	The specified `templateSlug` does not match any template in your account
429	`rate_limit_exceeded`	Too many requests. See Rate Limits.
500	`internal_error`	An 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",
    "details": null
  }
}

Next Steps

Topic	Description
Posts API	Use rendered images in post submissions
Media API	Upload other media for use in posts
OG Image Templates	Learn how to create and configure templates in the dashboard

API Reference

Templates api

Templates API

Render a Template

Authentication

Headers

Rate Limit

Request Body

Config Object

Response

Examples

Render a tweet image template

Render with a custom aspect ratio

Using the alias endpoint

Render and publish in one workflow

Error Responses

Next Steps

​Templates API

​Render a Template

​Authentication

​Headers

​Rate Limit

​Request Body

​Config Object

​Response

​Examples

​Render a tweet image template

​Render with a custom aspect ratio

​Using the alias endpoint

​Render and publish in one workflow

​Error Responses

​Next Steps

Templates API

Render a Template

Authentication

Headers

Rate Limit

Request Body

Config Object

Response

Examples

Render a tweet image template

Render with a custom aspect ratio

Using the alias endpoint

Render and publish in one workflow

Error Responses

Next Steps