Endpoint Group: Conversion Options

Every converter supports a different set of options — resize, compression, OCR, metadata stripping, and more. Use the schema endpoints to discover exactly what a converter accepts before submitting a job.

Endpoints

• GET /convert/schema — Full options schema covering every option across all converters
• GET /convert/schema/{from}/{to} — Filtered schema with only the options that apply to a specific conversion

Auth

Requires X-Fast-Api-Key header.

Path params

• from: source format (e.g. heic, pdf, otf)
• to: target format (e.g. jpg, png, woff2)

Response

200 OK with content type application/schema+json. The response is a standard JSON Schema (draft 2020-12) document.

Example: converter with options (HEIC to JPG)

GET /convert/schema/heic/jpg

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for heic to jpg conversion (job type: image.heic-to-jpg)",
  "properties": {
    "resize": {
      "type": "object",
      "description": "Resize image by pixels or percentage with presets (4K, 1080p, 720p, custom)",
      "properties": {
        "enabled": { "type": "boolean" },
        "mode": {
          "type": "string",
          "enum": ["pixels", "percentage"],
          "description": "Resize mode: 'pixels' targets longest edge, 'percentage' scales proportionally."
        },
        "preset": {
          "type": "string",
          "enum": ["off", "4k", "2k", "1080p", "720p", "custom"],
          "description": "Resize preset. Use 'custom' with mode and value for precise control.",
          "default": "off"
        },
        "value": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "description": "Target size when preset is 'custom'. Pixels = longest edge; percentage = scale factor (e.g. 50 = 50%)."
        }
      }
    },
    "smartCompression": {
      "type": "object",
      "description": "Optimize file size using format-specific compression (MozJPEG, pngquant, etc.)",
      "properties": {
        "enabled": { "type": "boolean" },
        "mode": {
          "type": "string",
          "enum": ["lossy", "lossless"],
          "default": "lossy"
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "EXIF/GPS metadata handling for privacy and file size reduction",
      "properties": {
        "strip": { "type": "boolean", "default": true }
      }
    }
  },
  "additionalProperties": false
}

Example: converter with no options (OTF to WOFF2)

GET /convert/schema/otf/woff2

Font conversions have no configurable options — the response has empty properties:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for otf to woff2 conversion (job type: font.otf-to-woff2)",
  "properties": {},
  "additionalProperties": false
}

Examples

# Full schema (all possible options)
curl -sS "https://api.tools.fast/convert/schema" \
  -H "X-Fast-Api-Key: $API_KEY"

# Converter-specific schema (only options that apply)
curl -sS "https://api.tools.fast/convert/schema/heic/jpg" \
  -H "X-Fast-Api-Key: $API_KEY"

# Converter with no options (e.g. font conversion)
curl -sS "https://api.tools.fast/convert/schema/otf/woff2" \
  -H "X-Fast-Api-Key: $API_KEY"

# Unsupported format pair (returns 400)
curl -sS "https://api.tools.fast/convert/schema/heic/mp3" \
  -H "X-Fast-Api-Key: $API_KEY"

# Full schema (all possible options)
Invoke-RestMethod "https://api.tools.fast/convert/schema" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY }

# Converter-specific schema (only options that apply)
Invoke-RestMethod "https://api.tools.fast/convert/schema/heic/jpg" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY }

# Converter with no options (e.g. font conversion)
Invoke-RestMethod "https://api.tools.fast/convert/schema/otf/woff2" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY }

# Unsupported format pair (returns 400)
Invoke-RestMethod "https://api.tools.fast/convert/schema/heic/mp3" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY }

Error responses

400 Bad Request when the format pair is not supported.

Example: unsupported format pair

{
  "error": "schema.unsupported_format_pair",
  "detail": "Conversion from 'heic' to 'mp3' is not supported.",
  "sourceFormat": "heic",
  "targetFormat": "mp3",
  "supportedTargets": ["avif", "jpg", "png", "webp"]
}

Example: unsupported source format

{
  "error": "schema.unsupported_source_format",
  "detail": "No converters found for source format 'xyz'.",
  "sourceFormat": "xyz",
  "supportedTargets": []
}