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