ConverterHQDevelopers
API v1

Opsi konversi

Sebelum mengirim setting, panggil GET /v1/capabilities/<from>/to/<to>.

Setting konversi bersifat spesifik per pasangan dan berasal dari kontrak bertipe yang sama dengan yang dipakai worker. Setting dimiliki oleh satu Task konversi, bukan oleh langkah engine internal.

Model setting

Setiap pasangan input/output yang didukung memiliki kontrak capability. Kontrak publik hanya mengekspos setting yang dapat diterapkan secara tidak ambigu pada Task tersebut; nama langkah internal bukan bagian dari API v1.

Menemukan setting yang berlaku

Sebelum mengirim setting, panggil GET /v1/capabilities/<from>/to/<to>. Respons berisi options, options_schema, options_version, settings_scope, dan metadata route. Hanya nama yang dikembalikan dalam options yang diterima untuk pasangan itu.

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

Konversi sederhana

API sederhana adalah satu namespace Task konversi implisit; nilai spesifik pasangan tetap langsung di bawah options dan hanya diproyeksikan ke langkah internal yang menyatakan bahwa mereka mengonsumsinya.

Konversi sederhana
POST /v1/convert/png/to/webp

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

Namespace Task bernama

Dalam Job, setiap Task convert bernama memiliki options.settings sendiri. Jika beberapa tahap memerlukan nilai berbeda, buat Task convert terpisah dan validasi setiap pasangan secara mandiri.

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

Setting yang bertabrakan

Jika beberapa langkah internal mengonsumsi nama setting yang sama, ConverterHQ tidak memilih berdasarkan urutan langkah. Field dihapus dari schema pasangan kecuali semua consumer secara eksplisit menyatakan broadcast aman dengan semantik yang sama. Jika tidak, gunakan Task bernama yang terpisah.

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

Validasi dan versioning

options_version mengidentifikasi schema pasangan saat ini. Gunakan POST /v1/jobs/validate untuk memvalidasi seluruh graph tanpa menjalankannya dan refresh capability daripada hard-code setting untuk pasangan arbitrer.