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