ConverterHQDevelopers
API v1

Opcje konwersji

Przed wysłaniem ustawień wywołaj GET /v1/capabilities/<from>/to/<to>.

Ustawienia konwersji są specyficzne dla pary i pochodzą z tych samych typowanych kontraktów, których używają workery. Należą do Task konwersji, a nie do ukrytych kroków silnika.

Model ustawień

Każda obsługiwana para wejście/wyjście ma kontrakt capability. Publiczny kontrakt pokazuje tylko ustawienia, które można jednoznacznie zastosować do tej Task; nazwy wewnętrznych kroków nie są częścią API v1.

Odkrywanie dostępnych ustawień

Przed wysłaniem ustawień wywołaj GET /v1/capabilities/<from>/to/<to>. Odpowiedź zawiera options, options_schema, options_version, settings_scope i metadane trasy. Dla pary akceptowane są wyłącznie nazwy zwrócone w 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"}
  ]
}

Proste konwersje

Proste API jest jednym niejawnym namespace Task konwersji; wartości specyficzne dla pary pozostają bezpośrednio w options i są przekazywane tylko do kroków wewnętrznych, które deklarują ich użycie.

Prosta konwersja
POST /v1/convert/png/to/webp

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

Namespace nazwanych Tasks

W Job każda nazwana Task convert ma własne options.settings. Jeśli różne etapy wymagają różnych wartości, utwórz osobne Tasks convert i waliduj każdą parę niezależnie.

Zadanie 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}
      }
    }
  }
}

Kolizje ustawień

Jeśli kilka ukrytych kroków zużywa tę samą nazwę ustawienia, ConverterHQ nie rozstrzyga kolizji kolejnością kroków. Pole jest usuwane ze schematu pary, chyba że wszyscy konsumenci jawnie deklarują bezpieczny broadcast o identycznej semantyce. W przeciwnym razie użyj osobnych nazwanych Tasks.

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

Walidacja i wersjonowanie

options_version identyfikuje bieżący schemat pary. Użyj POST /v1/jobs/validate, aby sprawdzić cały graph bez wykonania, i odświeżaj capabilities zamiast hard-code'ować ustawienia arbitralnych par.