ConverterHQDevelopers
API v1

Konvertierungsoptionen

Rufe vor dem Senden von Einstellungen GET /v1/capabilities/<from>/to/<to> auf.

Konvertierungseinstellungen sind paarbezogen und stammen aus denselben typisierten Verträgen wie die Worker. Sie gehören zu einer Convert-Task und niemals zu internen Engine-Schritten.

Einstellungsmodell

Jedes unterstützte Ein-/Ausgabe-Paar besitzt einen Capability-Vertrag. Der öffentliche Vertrag zeigt nur Einstellungen, die für diese Task eindeutig anwendbar sind; interne Schrittnamen gehören nicht zu API v1.

Anwendbare Einstellungen ermitteln

Rufe vor dem Senden von Einstellungen GET /v1/capabilities/<from>/to/<to> auf. Die Antwort enthält options, options_schema, options_version, settings_scope und Route-Metadaten. Nur Namen aus options werden für dieses Paar akzeptiert.

Capability
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"}
  ]
}

Einfache Konvertierungen

Die einfache API ist ein impliziter Convert-Task-Namespace. Paarbezogene Werte liegen direkt unter options und werden nur an interne Schritte weitergegeben, die sie ausdrücklich konsumieren.

Einfache Konvertierung
POST /v1/convert/png/to/webp

{
  "input": {"file_id": "file_..."},
  "options": {"quality": 90, "lossless": false}
}

Benannte Task-Namespaces

In einem Job besitzt jede benannte convert-Task ihr eigenes options.settings. Wenn mehrere Stufen unterschiedliche Werte benötigen, modellieren Sie sie als getrennte convert-Tasks und validieren Sie jedes Paar separat.

Job-Task
{
  "tasks": {
    "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}
      }
    }
  }
}

Kollidierende Einstellungen

Wenn mehrere versteckte Schritte denselben Einstellungsnamen konsumieren, löst ConverterHQ die Kollision nicht über die Schritt-Reihenfolge. Das Feld wird aus dem Paar-Schema entfernt, außer alle Verbraucher erlauben explizit sicheres Broadcasting mit identischer Semantik. Andernfalls verwenden Sie getrennte benannte Tasks.

Collision
{
  "settings_scope": "conversion-task",
  "route": {
    "multi_step": true,
    "requires_explicit_tasks_for": ["quality"]
  }
}

Validierung und Versionierung

options_version identifiziert das aktuelle Paar-Schema. Verwenden Sie POST /v1/jobs/validate, um einen vollständigen Task-Graph ohne Ausführung zu prüfen, und laden Sie Capability-Metadaten neu, statt Optionen für beliebige Paare fest zu codieren.