Skip to content
OG Engine logoOG Engine

POST /validate

Validates whether title and description text will fit within the specified format’s layout constraints. Returns line count, max lines, and overflow status for each text block. Does not generate an image.

POST https://og-engine.com/validate

Authentication: Optional — accepts Authorization: Bearer header but does not require it Cost: Free, unlimited, never metered against your plan quota

Request Body

Section titled “Request Body”
Field Type Required Default Description
format string Yes — og, twitter, square, linkedin, story
title string Yes — The title text to measure
description string No — The description text to measure
font string No "Outfit" Font family to use for measurement
titleSize number No 48 Title font size in pixels (28–72)
descSize number No 22 Description font size in pixels (14–32)
maxTitleLines number No 3 Maximum lines before title overflows
maxDescLines number No 4 Maximum lines before description overflows
autoFit boolean No false Auto-find optimal font sizes that prevent overflow

Example Request

Section titled “Example Request”
Terminal window
curl -X POST https://og-engine.com/validate \
  -H "Content-Type: application/json" \
  -d '{
    "format": "og",
    "title": "The Complete Guide to Building High-Performance APIs with Bun",
    "description": "A walkthrough covering routing, middleware, database access, caching, authentication, and deployment.",
    "font": "Outfit",
    "titleSize": 48,
    "descSize": 22
  }'

Response

Section titled “Response”
{
  "fits": true,
  "title": {
    "lines": 3,
    "maxLines": 3,
    "overflow": false
  },
  "description": {
    "lines": 3,
    "maxLines": 4,
    "overflow": false
  },
  "computeTimeMs": 0.18
}

Response Fields

Section titled “Response Fields”
Field Type Description
fits boolean true if both title and description are within limits
title.lines number Number of lines the title wraps to
title.maxLines number Maximum lines allowed (from request or default)
title.overflow boolean true if lines > maxLines
description.lines number Number of lines the description wraps to
description.maxLines number Maximum lines allowed
description.overflow boolean true if lines > maxLines
computeTimeMs number Time taken to measure the text in milliseconds

Overflow Example

Section titled “Overflow Example”
Terminal window
curl -X POST https://og-engine.com/validate \
  -H "Content-Type: application/json" \
  -d '{
    "format": "og",
    "title": "An Extremely Long Title That Will Definitely Overflow The Available Space In The Layout Engine",
    "description": "A very long description that contains way too much information to fit in a standard OG image format."
  }'
{
  "fits": false,
  "title": {
    "lines": 4,
    "maxLines": 3,
    "overflow": true
  },
  "description": {
    "lines": 5,
    "maxLines": 4,
    "overflow": true
  },
  "computeTimeMs": 0.22
}

When fits is false, consider:

  • Using autoFit: true to let the engine find optimal font sizes automatically
  • Shortening the text
  • Reducing titleSize / descSize
  • Passing custom maxTitleLines / maxDescLines if your template allows more room

Auto-Fit Mode

Section titled “Auto-Fit Mode”

Set autoFit: true to let OG Engine find the largest font size that fits within the line limits. Uses binary search for optimal results.

Terminal window
curl -X POST https://og-engine.com/validate \
  -H "Content-Type: application/json" \
  -d '{
    "format": "og",
    "title": "A Very Long Title That Would Normally Overflow But AutoFit Finds The Right Size",
    "autoFit": true
  }'
{
  "fits": true,
  "autoFit": {
    "titleSize": 38,
    "descSize": 32
  },
  "title": {
    "lines": 3,
    "maxLines": 3,
    "overflow": false
  },
  "computeTimeMs": 0.45
}

Pass these fitted sizes to /render with style.autoFit: true to use the same algorithm at render time.

Custom Constraints Example

Section titled “Custom Constraints Example”
Terminal window
curl -X POST https://og-engine.com/validate \
  -H "Content-Type: application/json" \
  -d '{
    "format": "og",
    "title": "My Article Title",
    "description": "My article description.",
    "font": "Playfair Display",
    "titleSize": 52,
    "maxTitleLines": 2,
    "maxDescLines": 3
  }'

Always match the font and size values you plan to use in /render — different fonts have different metrics and will produce different line counts.

Error Responses

Section titled “Error Responses”
Status Code Cause
400 missing_field format or title not provided
400 invalid_format format is not a recognized value
400 invalid_font font is not a supported font family

Next Steps

Section titled “Next Steps”