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

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

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

{
  "fits": true,
  "title": {
    "lines": 3,
    "maxLines": 3,
    "overflow": false
  },
  "description": {
    "lines": 3,
    "maxLines": 4,
    "overflow": false
  },
  "computeTimeMs": 0.18
}

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

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

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

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

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

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

• Generating Images — use /render once validation passes
• Text Validation Guide — form integration patterns and auto font-sizing
• POST /render — full render endpoint reference