ConverterHQDevelopers
API v1

Opções de conversão

Antes de enviar settings, chame GET /v1/capabilities/<from>/to/<to>.

As configurações de conversão são específicas de cada par e vêm dos mesmos contratos tipados usados pelos workers. Elas pertencem a uma Task de conversão, nunca às etapas internas do engine.

Modelo de settings

Cada par de entrada/saída suportado tem um contrato de capability. O contrato público expõe apenas settings que podem ser aplicados sem ambiguidade àquela Task; nomes de etapas internas não fazem parte da API v1.

Descobrir settings aplicáveis

Antes de enviar settings, chame GET /v1/capabilities/<from>/to/<to>. A resposta inclui options, options_schema, options_version, settings_scope e metadados da rota. Somente nomes retornados em options são aceitos para o par.

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

Conversões simples

A API simples representa um único namespace implícito de Task de conversão; valores específicos do par ficam diretamente em options e são projetados apenas para as etapas internas que os consomem.

Conversão simples
POST /v1/convert/png/to/webp

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

Namespaces de Tasks nomeadas

Em um Job, cada Task convert nomeada possui seu próprio options.settings. Quando etapas diferentes exigirem valores diferentes, crie Tasks convert separadas e valide cada par de forma independente.

Tarefa do 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}
      }
    }
  }
}

Settings em colisão

Se várias etapas internas consomem o mesmo nome de setting, o ConverterHQ não resolve a colisão pela ordem das etapas. O campo é removido do schema do par, a menos que todos os consumidores declarem explicitamente que o broadcast é seguro e possui a mesma semântica. Caso contrário, use Tasks nomeadas separadas.

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

Validação e versionamento

options_version identifica o schema atual do par. Use POST /v1/jobs/validate para validar um grafo completo sem executá-lo e atualize capabilities em vez de codificar settings de pares arbitrários.