ConverterHQDevelopers
API v1

Opzioni di conversione

Prima di inviare impostazioni, chiama GET /v1/capabilities/<from>/to/<to>.

Le impostazioni di conversione sono specifiche della coppia e derivano dagli stessi contratti tipizzati usati dai worker. Appartengono a una Task di conversione, non ai passaggi interni dell'engine.

Modello delle impostazioni

Ogni coppia input/output supportata ha un contratto di capability. Il contratto pubblico espone solo impostazioni applicabili senza ambiguità a quella Task; i nomi dei passaggi interni non fanno parte dell'API v1.

Scoprire le impostazioni applicabili

Prima di inviare impostazioni, chiama GET /v1/capabilities/<from>/to/<to>. La risposta include options, options_schema, options_version, settings_scope e metadati della route. Per la coppia sono accettati solo i nomi restituiti in options.

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

Conversioni semplici

L'API semplice rappresenta un unico namespace implicito di Task di conversione; i valori specifici della coppia restano direttamente in options e vengono proiettati solo sui passaggi interni che li consumano.

Conversione semplice
POST /v1/convert/png/to/webp

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

Namespace di Task nominate

In un Job ogni Task convert nominata possiede il proprio options.settings. Se fasi diverse richiedono valori diversi, crea Task convert separate e valida ogni coppia indipendentemente.

Task del 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}
      }
    }
  }
}

Impostazioni in collisione

Se più passaggi interni consumano lo stesso nome di impostazione, ConverterHQ non risolve la collisione in base all'ordine. Il campo viene escluso dallo schema della coppia salvo che tutti i consumer dichiarino esplicitamente un broadcast sicuro con semantica identica. Altrimenti usa Task nominate separate.

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

Validazione e versioning

options_version identifica lo schema corrente della coppia. Usa POST /v1/jobs/validate per validare un grafo completo senza eseguirlo e aggiorna le capability invece di codificare impostazioni per coppie arbitrarie.