{
  "openapi": "3.1.0",
  "info": {
    "title": "Placeho",
    "version": "1.0.0",
    "description": "Free placeholder images and responsive or social media safe zones by URL. No key needed."
  },
  "servers": [
    {
      "url": "https://placeho.com"
    }
  ],
  "paths": {
    "/{size}": {
      "get": {
        "operationId": "placeholderImage",
        "summary": "Placeholder SVG image",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "description": "WIDTHxHEIGHT like 600x400, a single number for a square, or a named format like tiktok, instagram-reels, youtube-shorts, vertical-video",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "text",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Text on the image. Use \\n for a new line."
          },
          {
            "name": "guides",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated social guide ids: reels, stories, fbreels, tiktok, shorts, grid, fbcover-desktop, fbcover-mobile, ytbanner-desktop, ytbanner-mobile, ytbadge"
          },
          {
            "name": "crops",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated aspect ratios for responsive crops, like 16:9,4:3,4:5"
          },
          {
            "name": "focus",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Focal point as x,y percentages, like 20,50"
          },
          {
            "name": "pad",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 25
            },
            "description": "Text-safe inset inside the safe zone, in percent (default 8)"
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image",
            "content": {
              "image/svg+xml": {}
            }
          }
        }
      }
    },
    "/{size}/{background}/{color}": {
      "get": {
        "operationId": "placeholderImageWithColours",
        "summary": "Placeholder SVG with background and text colour",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "background",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Hex without # or a CSS colour name"
          },
          {
            "name": "color",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Hex without # or a CSS colour name"
          },
          {
            "name": "text",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image",
            "content": {
              "image/svg+xml": {}
            }
          }
        }
      }
    },
    "/api/safe-zone/{size}": {
      "get": {
        "operationId": "safeZone",
        "summary": "Safe zone as JSON",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "WIDTHxHEIGHT or a named format like tiktok"
          },
          {
            "name": "guides",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "crops",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "focus",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pad",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Safe zone in pixels and percent",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/api/formats": {
      "get": {
        "operationId": "listFormats",
        "summary": "All named formats with sizes and safe zones",
        "responses": {
          "200": {
            "description": "List of formats",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  }
}