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