ConverterHQDevelopers
API v1

Conversie-opties

Roep vóór het versturen van instellingen GET /v1/capabilities/<from>/to/<to> aan.

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.

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

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.

Eenvoudige conversie
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.

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

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