ConverterHQDevelopers
Documentation

Conversion options

Discover pair-specific settings, task namespaces and collision rules from the live capability contract.

Conversion settings are pair-specific and generated from the same typed contracts used by ConverterHQ workers. Unknown options are rejected before execution so misspellings cannot silently fall back to defaults. Settings belong to a conversion task, not to ConverterHQ's hidden engine steps.

Settings model

Every supported input/output pair has a capability contract. The public contract exposes only settings that can be applied unambiguously to that conversion task. Internal routes may contain one or many engine steps, but those hidden step names are not part of API v1 and must never be used as public namespaces.

Discover applicable settings

Before sending settings, call GET /v1/capabilities/<from>/to/<to>. The response includes options, strict options_schema, options_version, settings_scope, and route metadata. Only names returned in options are accepted for that pair.

Capability discovery
GET /v1/capabilities/png/to/webp

{
  "supported": true,
  "settings_scope": "conversion-task",
  "route": {
    "multi_step": false,
    "requires_explicit_tasks_for": []
  },
  "options_version": "...",
  "options": [
    {"name": "quality", "type": "integer"},
    {"name": "lossless", "type": "boolean"},
    {"name": "resize", "type": "object"}
  ]
}

For catalogue discovery, use GET /v1/capabilities with optional input/output filters. Add ?include=options for rendering metadata or ?include=options.details for full JSON Schema. The Conversion Explorer uses the same endpoint.

Simple conversions

Simple conversion
POST /v1/convert/png/to/webp

{
  "input": {"file_id": "file_..."},
  "options": {
    "quality": 90,
    "lossless": false,
    "resize": {"width": 1600, "height": 900}
  }
}

The simple conversion endpoint is one implicit conversion-task namespace, so its pair-specific settings stay directly under options. ConverterHQ projects those values only to the hidden engine steps that declare that they consume them.

Named task namespaces

Per-task settings
{
  "tasks": {
    "source": {
      "operation": "import/url",
      "input": {"url": "https://example.com/report.docx"}
    },
    "document": {
      "operation": "convert",
      "input": "source",
      "options": {
        "input_format": "docx",
        "output_format": "pdf",
        "settings": {"optimize": true, "linearize": true}
      }
    },
    "preview": {
      "operation": "convert",
      "input": "document",
      "options": {
        "input_format": "pdf",
        "output_format": "jpg",
        "settings": {"dpi": 180, "quality": 82}
      }
    }
  }
}

document.settings and preview.settings are independent namespaces. ConverterHQ validates each Task against that Task's exact input/output capability before the Job is accepted.

Colliding settings

A hidden multi-step route can contain more than one engine step that uses the same setting name. ConverterHQ does not resolve that collision by step order. A colliding field is omitted from the pair-level settings schema unless every consuming step explicitly declares the field safe to broadcast with identical semantics.

Collision metadata
{
  "supported": true,
  "settings_scope": "conversion-task",
  "route": {
    "multi_step": true,
    "requires_explicit_tasks_for": ["quality"]
  },
  "options": [
    {"name": "resize", "type": "object"}
  ]
}

In this example quality is intentionally not accepted on the implicit pair. To choose separate quality values, split the workflow into named conversion Tasks whose individual pair capabilities expose an unambiguous quality option.

Validation and versioning

options_version identifies the current settings schema for the pair. Existing v1 option names keep their type and default semantics; new optional settings may be added. Use POST /v1/jobs/validate to validate a complete Task graph without executing it, and refresh capability metadata rather than hard-coding settings for arbitrary pairs.

The same capability contract drives the website settings dialog, Conversion Explorer, OpenAPI/SDK tooling, Job Builder, MCP capability tools and Zapier dynamic fields.