Aspect ratio fit/cover API

Simplifies w:h to lowest terms, names common ratios, and fits a source box into a target with both contain and cover, reporting letterbox/pillarbox bars and crop overflow. Answers 'What is 1920x1080 as a ratio and how does it fit a 1000x1000 box?', 'How big are the letterbox bars?'.

Price$0.04per request

MethodPOST

Route/v1/design/aspect-ratio

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

designlayoutaspect-ratiocontaincoverletterboxcropfit

API URLhttps://x402.hexl.dev/v1/design/aspect-ratio

Integration docs

Example request

{
  "width": 1920,
  "height": 1080,
  "targetWidth": 1000,
  "targetHeight": 1000
}

Example response

{
  "width": 1920,
  "height": 1080,
  "ratio": 1.77778,
  "simplified": "16:9",
  "name": "widescreen HD",
  "orientation": "landscape",
  "fit": {
    "contain": {
      "scale": 0.52083,
      "width": 1000,
      "height": 562.5,
      "letterboxBarsPx": 218.75,
      "pillarboxBarsPx": 0
    },
    "cover": {
      "scale": 0.92593,
      "width": 1777.778,
      "height": 1000,
      "cropXEachSide": 388.889,
      "cropYEachSide": 0
    }
  },
  "interpretation": "1920×1080 simplifies to 16:9 (widescreen HD)."
}

Input schema

{
  "type": "object",
  "required": [
    "width",
    "height"
  ],
  "properties": {
    "width": {
      "type": "number",
      "description": "Source width",
      "examples": [
        1920
      ]
    },
    "height": {
      "type": "number",
      "description": "Source height",
      "examples": [
        1080
      ]
    },
    "targetWidth": {
      "type": "number",
      "description": "Target box width for fit calc (optional)",
      "examples": [
        1000
      ]
    },
    "targetHeight": {
      "type": "number",
      "description": "Target box height for fit calc (optional)",
      "examples": [
        1000
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}