Render API Docs

Create social post and carousel images from structured JSON. This API is deterministic: clients provide the design document, and the server renders images.

Render Schema OpenAPI JSON Visual Editor

Endpoint Summary

Endpoint Use
GET /api/health Deployment smoke test endpoint.
GET /api/render-schema Machine-readable contract with platforms, brands, enums, examples, and field schema.
GET /api/openapi.json OpenAPI document for LLM tools, SDK generation, and API clients.
POST /api/render Returns JSON with image data URLs, temporary URLs, or both.
POST /api/render.png Returns one rendered slide directly as image/png.
GET /api/assets/unsplash/search Search Unsplash image assets for backgrounds or overlays.
POST /api/assets/unsplash/track-download Track Unsplash download usage after selecting an image.
GET /api/assets/hugeicons/search Search icon assets for image overlays.

Asset Search Flow

Search/select an asset first, then pass the chosen renderUrl into the render request. Rendering stays deterministic and does not choose images automatically.

Search Unsplash

curl "http://localhost:8080/api/assets/unsplash/search?query=cocktail%20bar&target=background&per_page=6"

Use The Selected Image As A Background

curl -X POST http://localhost:8080/api/render.png \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram-post",
    "slides": [
      {
        "image": "SELECTED_UNSPLASH_RENDER_URL",
        "textBlocks": [
          {
            "text": "Tonight at The Bar",
            "fontSize": 48,
            "style": "bold",
            "textColor": "#FFFFFF",
            "x": 44,
            "y": 120,
            "maxWidth": 330
          }
        ]
      }
    ]
  }' \
  --output post.png

Use The Selected Image As An Overlay

curl -X POST http://localhost:8080/api/render.png \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram-square",
    "slides": [
      {
        "backgroundColor": "#000000",
        "imageOverlays": [
          {
            "src": "SELECTED_UNSPLASH_RENDER_URL",
            "name": "Cocktail image",
            "x": 80,
            "y": 120,
            "width": 220,
            "height": 220,
            "cropX": 50,
            "cropY": 50,
            "borderRadius": 24
          }
        ]
      }
    ]
  }' \
  --output overlay-post.png

Track Unsplash Download

curl -X POST http://localhost:8080/api/assets/unsplash/track-download \
  -H 'Content-Type: application/json' \
  -d '{
    "downloadLocation": "SELECTED_UNSPLASH_ATTRIBUTION_DOWNLOAD_LOCATION"
  }'

Direct PNG

Use this when a caller wants the final image file directly.

curl -X POST http://localhost:8080/api/render.png \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram-square",
    "slides": [
      {
        "backgroundColor": "#111111",
        "textBlocks": [
          {
            "text": "Direct PNG",
            "fontSize": 48,
            "style": "highlight",
            "highlightColor": "#D4AF37",
            "textColor": "#000000",
            "x": 44,
            "y": 190,
            "maxWidth": 320
          }
        ]
      }
    ]
  }' \
  --output post.png

Carousel Slide PNG

Use the slide query parameter to return a specific 1-based slide from a carousel request.

curl -X POST 'http://localhost:8080/api/render.png?slide=2' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram-post",
    "mode": "carousel",
    "stepperStyle": "bars",
    "slides": [
      {
        "backgroundColor": "#000000",
        "textBlocks": [
          {
            "text": "Slide one",
            "fontSize": 48,
            "style": "bold",
            "textColor": "#FFFFFF",
            "x": 44,
            "y": 120,
            "maxWidth": 320
          }
        ]
      },
      {
        "backgroundColor": "#D4AF37",
        "textBlocks": [
          {
            "text": "Slide two direct",
            "fontSize": 48,
            "style": "outline",
            "textColor": "#FFFFFF",
            "x": 44,
            "y": 120,
            "maxWidth": 320
          }
        ]
      }
    ]
  }' \
  --output slide-2.png

JSON Response

Use this when a caller wants URLs, inline base64 data, or multiple carousel outputs in one response.

curl -X POST http://localhost:8080/api/render \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "instagram-square",
    "format": "png",
    "delivery": "url",
    "slides": [
      {
        "backgroundColor": "#111111",
        "textBlocks": [
          {
            "text": "Temporary URL",
            "fontSize": 44,
            "style": "highlight",
            "highlightColor": "#D4AF37",
            "textColor": "#000000",
            "x": 44,
            "y": 190,
            "maxWidth": 320
          }
        ]
      }
    ]
  }'

Important Fields

Field Values Notes
platform instagram-square, instagram-post, instagram-story, tiktok-carousel, tiktok-story, linkedin-post, linkedin-portrait Controls export dimensions.
mode single, carousel single renders only the first slide.
delivery dataUrl, url, both Temporary URLs are cleaned up automatically and should be fetched immediately.
stepperStyle none, numeric, dots, dots-outline, bars, pills, line, minimal Only applies to carousel mode.
x, y Numbers in preview pixels Coordinates match the visual editor preview and are scaled to export size.

Limits And Errors

Requests outside the documented limits are rejected instead of being silently truncated.

Limit Value
Carousel slides 20
Text blocks per slide 30
Image overlays per slide 30
Remote image size 12 MB
JSON body size 2 MB by default 
{
  "error": {
    "code": "invalid_render_request",
    "message": "platform has an unsupported value.",
    "details": {}
  }
}