ConverterHQDevelopers
API v1

Dönüştürme seçenekleri

Ayar göndermeden önce GET /v1/capabilities/<from>/to/<to> çağrısını yapın.

Dönüştürme ayarları çift bazlıdır ve worker'ların kullandığı aynı tipli sözleşmelerden gelir. Ayarlar bir dönüştürme Task'ına aittir; gizli engine adımlarına ait değildir.

Ayar modeli

Desteklenen her input/output çifti bir capability sözleşmesine sahiptir. Public sözleşme yalnızca o Task'a belirsizlik olmadan uygulanabilen ayarları gösterir; dahili adım adları API v1'in parçası değildir.

Geçerli ayarları keşfetme

Ayar göndermeden önce GET /v1/capabilities/<from>/to/<to> çağrısını yapın. Yanıt options, options_schema, options_version, settings_scope ve route metadatasını içerir. Çift için yalnızca options içinde dönen adlar kabul edilir.

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

Basit dönüşümler

Basit API tek bir örtük dönüştürme-Task namespace'idir; çifte özgü değerler doğrudan options altında kalır ve yalnızca bunları tükettiğini bildiren gizli adımlara aktarılır.

Basit dönüşüm
POST /v1/convert/png/to/webp

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

Adlandırılmış Task namespace'leri

Bir Job içinde her adlandırılmış convert Task kendi options.settings alanına sahiptir. Farklı aşamalar farklı değerler gerektiriyorsa ayrı convert Task'ları oluşturun ve her çifti bağımsız doğrulayın.

Job görevi
{
  "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}
      }
    }
  }
}

Çakışan ayarlar

Birden fazla gizli adım aynı ayar adını tüketiyorsa ConverterHQ bunu adım sırasına göre çözmez. Tüm tüketiciler aynı semantik ile güvenli broadcast'i açıkça bildirmedikçe alan çift şemasından çıkarılır. Aksi halde ayrı adlandırılmış Task'lar kullanın.

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

Doğrulama ve versiyonlama

options_version çiftin mevcut şemasını tanımlar. Tam Task graph'ını çalıştırmadan doğrulamak için POST /v1/jobs/validate kullanın ve rastgele çiftlerin ayarlarını hard-code etmek yerine capability bilgisini yenileyin.