ConverterHQDevelopers
API v1

Options de conversion

Appelez GET /v1/capabilities/<from>/to/<to> avant d'envoyer des paramètres.

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.

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

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.

Conversion simple
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.

Tâche Job
{
  "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.

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