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.
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.
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.
{
"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.
{
"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.