Les paramètres de conversion sont propres à chaque paire et proviennent des mêmes contrats typés que ceux utilisés par les workers. Ils appartiennent à une Task de conversion, jamais aux étapes internes du moteur.
Modèle des paramètres
Chaque paire entrée/sortie prise en charge possède un contrat de capability. Le contrat public n'expose que les paramètres applicables sans ambiguïté à cette Task; les noms des étapes internes ne font pas partie de l'API v1.
Découvrir les paramètres applicables
Appelez GET /v1/capabilities/<from>/to/<to> avant d'envoyer des paramètres. La réponse fournit options, options_schema, options_version, settings_scope et les métadonnées de route. Seuls les noms présents dans options sont acceptés pour cette paire.
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"}
]
}Conversions simples
L'API simple représente un seul namespace implicite de Task de conversion; les paramètres propres à la paire restent directement dans options et sont projetés uniquement vers les étapes internes qui les consomment.
POST /v1/convert/png/to/webp
{
"input": {"file_id": "file_..."},
"options": {"quality": 90, "lossless": false}
}Namespaces de Tasks nommées
Dans un Job, chaque Task convert nommée possède son propre options.settings. Pour contrôler plusieurs étapes avec des valeurs différentes, créez plusieurs Tasks convert et validez chaque paire séparément.
{
"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}
}
}
}
}Paramètres en collision
Si plusieurs étapes internes consomment le même nom de paramètre, ConverterHQ ne choisit pas selon l'ordre des étapes. Le champ est retiré du schéma de paire sauf si toutes les étapes concernées déclarent explicitement qu'un broadcast est sûr avec la même sémantique. Sinon, utilisez des Tasks nommées distinctes.
{
"settings_scope": "conversion-task",
"route": {
"multi_step": true,
"requires_explicit_tasks_for": ["quality"]
}
}Validation et versioning
options_version identifie le schéma actuel de la paire. Utilisez POST /v1/jobs/validate pour valider un graphe complet sans l'exécuter et actualisez les capabilities plutôt que de coder en dur les options de paires arbitraires.