Conversie-instellingen zijn paarspecifiek en komen uit dezelfde getypeerde contracten als de workers. Ze horen bij een conversie-Task, niet bij verborgen engine-stappen.
Instellingenmodel
Elk ondersteund input/output-paar heeft een capability-contract. Het publieke contract toont alleen instellingen die ondubbelzinnig op die Task kunnen worden toegepast; interne stapnamen maken geen deel uit van API v1.
Toepasselijke instellingen ontdekken
Roep vóór het versturen van instellingen GET /v1/capabilities/<from>/to/<to> aan. De response bevat options, options_schema, options_version, settings_scope en route-metadata. Alleen namen uit options worden voor dat paar geaccepteerd.
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"}
]
}Eenvoudige conversies
De eenvoudige API is één impliciete conversie-Task-namespace; paarspecifieke waarden staan direct onder options en worden alleen naar interne stappen gestuurd die ze expliciet consumeren.
POST /v1/convert/png/to/webp
{
"input": {"file_id": "file_..."},
"options": {"quality": 90, "lossless": false}
}Namespaces van benoemde Tasks
In een Job heeft elke benoemde convert-Task zijn eigen options.settings. Als verschillende stadia verschillende waarden nodig hebben, maak dan afzonderlijke convert-Tasks en valideer elk paar apart.
{
"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}
}
}
}
}Botsende instellingen
Als meerdere verborgen stappen dezelfde instelling consumeren, kiest ConverterHQ niet op basis van stapvolgorde. Het veld verdwijnt uit het paarschema tenzij alle consumers expliciet aangeven dat broadcast veilig is met identieke semantiek. Gebruik anders afzonderlijke benoemde Tasks.
{
"settings_scope": "conversion-task",
"route": {
"multi_step": true,
"requires_explicit_tasks_for": ["quality"]
}
}Validatie en versiebeheer
options_version identificeert het huidige paarschema. Gebruik POST /v1/jobs/validate om een volledige Task-graph te valideren zonder uitvoering en ververs capabilities in plaats van instellingen voor willekeurige paren hard te coderen.