ConverterHQDevelopers
API v1

Opciones de conversión

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

Los ajustes de conversión son específicos de cada par y proceden de los mismos contratos tipados que usan los workers. Pertenecen a una Task de conversión, nunca a los pasos internos del motor.

Modelo de settings

Cada par de entrada/salida compatible tiene un contrato de capability. El contrato público solo expone settings que pueden aplicarse sin ambigüedad a esa Task; los nombres de pasos internos no forman parte de API v1.

Descubrir settings aplicables

Antes de enviar settings, llama a GET /v1/capabilities/<from>/to/<to>. La respuesta incluye options, options_schema, options_version, settings_scope y metadatos de ruta. Solo se aceptan para el par los nombres devueltos en 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"}
  ]
}

Conversiones simples

La API simple representa un único namespace implícito de Task de conversión; los valores específicos del par se mantienen directamente en options y se proyectan solo a los pasos internos que los consumen.

Conversión simple
POST /v1/convert/png/to/webp

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

Namespaces de Tasks con nombre

En un Job, cada Task convert con nombre posee su propio options.settings. Si distintas etapas necesitan valores distintos, crea Tasks convert separadas y valida cada par de forma independiente.

Tarea del 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 en colisión

Si varios pasos internos consumen el mismo nombre de setting, ConverterHQ no lo resuelve por orden de pasos. El campo se elimina del esquema del par salvo que todos los consumidores declaren explícitamente que el broadcast es seguro y semánticamente idéntico. En caso contrario, usa Tasks con nombre separadas.

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

Validación y versionado

options_version identifica el esquema actual del par. Usa POST /v1/jobs/validate para validar un grafo completo sin ejecutarlo y vuelve a consultar capabilities en lugar de codificar settings de pares arbitrarios.