{
  "openapi": "3.1.1",
  "info": {
    "title": "Image Compressor API",
    "version": "1.0.0",
    "summary": "Shrink JPG, PNG, WebP, AVIF or GIF images: convert, resize, strip metadata and compare sizes.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://imagecompressor.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Shrink JPG, PNG, WebP, AVIF or GIF images: convert, resize, strip metadata and compare sizes.",
        "description": "Re-encodes an image as WebP, AVIF, JPEG or PNG at the quality you choose, optionally scales it down to a maximum width or height and removes metadata such as GPS location. Shows the before/after size, the saving and the new dimensions, with a preview and a download.\n\nMethodology:\n- The file type is detected from its first bytes, not from the file name; only JPEG, PNG, WebP, AVIF and GIF are accepted. For animated GIFs only the first frame is used.\n- ImageMagick decodes the image, applies the EXIF orientation, optionally scales it down (never up) to fit the maximum width/height, and encodes it in the chosen format. AVIF is encoded with libavif (avifenc) when it is installed.\n- Quality is passed to the encoder as is (1–100). PNG output is lossless, so quality does not apply; PNG is usually larger than WebP/AVIF for photos.\n- With \"Remove metadata\" on, EXIF/XMP/IPTC data (including GPS location and camera details), comments and embedded profiles are removed. Timestamps are never written, so the same input always gives the same file.\n- Files are processed in a private temporary folder that is deleted right after processing. The result is kept for about 2 hours so you can download it, then deleted.\n\nLossy formats (WebP, AVIF, JPEG) discard detail; keep your original.",
        "tags": [
          "media"
        ],
        "x-mcp-tool": "image_compressor",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageCompressorInput"
              },
              "examples": {
                "example1": {
                  "summary": "PNG gradient to WebP",
                  "value": {
                    "file": {
                      "filename": "gradient.png",
                      "contentType": "image/png",
                      "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAADAAAAAgEAIAAACLJrAIAAAAvElEQVRo3u3ZIRLDMAxE0XZmPSqzUA4W3h40uVRwQgqEJcEE/HcCg7W1tt/Lsq7H8UJCNsd2fe9exnPJXPv5u3sZz0WCGrI5SFBBNrWdJCgl87FdJCgVW4wEpWRzbJxBOZmLKVZgijVii5GglGyOnSmWkzk9qBJXDRKUogc19HHRgwpxSJOgFE26IXN6UEU2RQ8q0KQb3MUa8WBGglLx5EqCUvSgRox5EpTiV6PBe1CDHtSQOT2oIpv8alT+GThGqh2cdAQAAAAASUVORK5CYII="
                    },
                    "format": "webp",
                    "quality": 75
                  }
                },
                "example2": {
                  "summary": "JPEG photo to a smaller JPEG, max 64 px wide",
                  "value": {
                    "file": {
                      "filename": "sunset.jpg",
                      "contentType": "image/jpeg",
                      "contentBase64": "/9j/4AAQSkZJRgABAQAAAAAAAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/2wBDAQMDAwQDBAgEBAgQCwkLEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBD/wAARCABAAGADAREAAhEBAxEB/8QAGgABAQEBAQEBAAAAAAAAAAAABgUEAAIDCP/EAB8QAAICAgMBAQEAAAAAAAAAAAEEABECIQMFMTISIv/EABkBAQEBAQEBAAAAAAAAAAAAAAYFBAADB//EAB4RAAIDAQEBAQEBAAAAAAAAAAAEAQIDETESIUFh/9oADAMBAAIRAxEAPwD8jz7wBzUquc8rImFreKRyDYvj9T2S2mndahpprhfWWLKqV1qHmXC5gqU+BCwP5kbZ0q5KGrHr9eTDZ7/TXVM7Lr9eTqvf6dZMy86FA/zN2Lpk1UJjSVXqWVnCVuqRnE6vUQqtdIbKxEbXOGVgRKrvF45JAYx+Z7Blm4xnrjw/eYE89LfFenpnX6sXEV/NQ07vzpfUxECSt1qFHGRIrgXU07rUMNNcECyxYXRsfMgMO8/pbxVN2HX2PmTLv/vpvqmdn19D5nUf/fTrJmFhGh8ymu73+mDZUjuJ1epfVa6RGViE6rV6idNkPtYB95f3UVpb94G28SHyYfjMiJc7fdekDSvzY0JYfrK5lcvyOGhWvZEaHF5B72vooUzEiHADWoQd2FCmQiRXBrUJOsc6JlcS8mndahZtvghWW6VeJAEfMh6vckr5p9g7lQAHzOye7J2ifIJTidXqXFG+khlbhBeXAvUUpMd4HmsQ6/wAXqLUtgy3kG3+L2L0dfAu3mHHcPzlcYJ37HAu1Xkn168eTwfk9048E3X4jUFv29FScCbr8RqDXreipOom6/AGoNfvP6Kk6iVDiBqDXtZgUp5xIhUUGYAAhVpqaSJF14tBzagwBBE5VqbycwvFYDz/ABAXFSOsyG3M4gNdhgBcZIXn8CzlQz2GI3GSNvAq5UM9hiNxkhbwKuR6GewHsaIyFXI9O68+Tn4OTnwTdfkNQW/X0VJyJuvyGoNer6Kk7Cbr8wKg1+k/oqTsJUOUCoNeymRSnpECFRsYAEGFWlZvIkXYisHNtjMEkzlVZpJzDEWgPP8AKDcVI5TAbc0iQ12GYNxkhSfwLOWDPYZDcZI18Crlgz2GQ3GSFfAq5PoZ7A+xojAVcn0+SWf5yqe7lOx08FbckRocvkHvZeihTQSIc4FbhB3EUKaiJFgCtwk6v3omV2LyblVuFm1OiFZnhV4nwB9SHqj2Svm5yDuV8EfU7JHknaOdglOOXe5cUU4SGWekF5gG9xSkvzgea2Dr/ODe4tSxDLeobf5fYvRy8C7egcdz/WVRgnTkdC7VuyZ+PP8AGYM1aV+68M+dvmxcRY83DTuHel9TYQJNVW4UcWEiu5dTcqtww0r0QLMlhd6h9SAwl3+FvFo3YdhQ+pMuh++G+rh2fYWPqdRD98Os4YWHrH1Ka6XP4YNmiO45d7l9VXhEZZITrV3uJ01g+1uH3mPdxWlhzgbb2IfJn+8yYlzr8V4QNLfVjzPQ8zUqwcMqJmFrCLx2DYvt8zyS2m5VbhppXpfWZLKrtVuHmUy5g0U+B+gP6kbZIq5NmrHsNezDZH/DXVw7LsNezqo/4dZwy879g/1N2KRk1bJjTt3uWVkyVu0RnHLvcQqq8IbLJEbYOeVAxKrhFI7JAY2+p5Blm4xn/9k="
                    },
                    "format": "jpeg",
                    "quality": 60,
                    "maxWidth": 64
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageCompressorResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ImageCompressorInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "file": {
            "title": "Image",
            "description": "JPG, PNG, WebP, AVIF or GIF (first frame), max 30 MB. Processed on our server and deleted; the result can be downloaded for about 2 hours. Upload as {filename, contentType?, contentBase64}. Max 30720 KiB. Accepts .jpg,.jpeg,.png,.webp,.avif,.gif,image/jpeg,image/png,image/webp,image/avif,image/gif.",
            "type": "object",
            "additionalProperties": false,
            "required": [
              "filename",
              "contentBase64"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "contentType": {
                "type": "string"
              },
              "contentBase64": {
                "type": "string"
              }
            }
          },
          "format": {
            "title": "Output format",
            "type": "string",
            "enum": [
              "webp",
              "avif",
              "jpeg",
              "png"
            ],
            "default": "webp"
          },
          "quality": {
            "title": "Quality",
            "description": "1 = smallest file, 100 = best quality. Ignored for PNG, which is always lossless.",
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 75
          },
          "maxWidth": {
            "title": "Maximum width",
            "description": "Optional. Larger images are scaled down proportionally; smaller ones are never enlarged.",
            "type": "integer",
            "minimum": 1,
            "maximum": 20000,
            "x-unit": "px"
          },
          "maxHeight": {
            "title": "Maximum height",
            "description": "Optional. Applied together with the maximum width.",
            "type": "integer",
            "minimum": 1,
            "maximum": 20000,
            "x-unit": "px"
          },
          "stripMetadata": {
            "title": "Remove metadata (EXIF, GPS location, camera details, colour profile comments)",
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "file"
        ]
      },
      "ImageCompressorResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "inputFormat",
              "outputFormat",
              "quality",
              "originalBytes",
              "outputBytes",
              "savingsPercent",
              "originalWidth",
              "originalHeight",
              "width",
              "height",
              "resized",
              "metadataStripped",
              "encoder",
              "artifact"
            ],
            "properties": {
              "inputFormat": {
                "type": "string",
                "enum": [
                  "jpeg",
                  "png",
                  "webp",
                  "avif",
                  "gif"
                ]
              },
              "outputFormat": {
                "type": "string",
                "enum": [
                  "webp",
                  "avif",
                  "jpeg",
                  "png"
                ]
              },
              "quality": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "null for PNG (lossless)"
              },
              "originalBytes": {
                "type": "integer"
              },
              "outputBytes": {
                "type": "integer"
              },
              "savingsPercent": {
                "type": "number",
                "description": "Positive = smaller than the original; negative = larger."
              },
              "originalWidth": {
                "type": "integer"
              },
              "originalHeight": {
                "type": "integer"
              },
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              },
              "resized": {
                "type": "boolean"
              },
              "metadataStripped": {
                "type": "boolean"
              },
              "encoder": {
                "type": "string"
              },
              "artifact": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "artifactId",
                  "filename",
                  "mime",
                  "bytes",
                  "sha256",
                  "path"
                ],
                "properties": {
                  "artifactId": {
                    "type": "string"
                  },
                  "filename": {
                    "type": "string"
                  },
                  "mime": {
                    "type": "string"
                  },
                  "bytes": {
                    "type": "integer"
                  },
                  "sha256": {
                    "type": "string"
                  },
                  "path": {
                    "type": "string",
                    "description": "Download path on the same site (valid for about 2 hours)."
                  }
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}