# Jobs

> Verifique, aguarde, liste e diagnostique jobs do Nodaro num assistente de IA: envelope, status, jobs retidos, falhas recuperáveis e modelos alternativos.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/jobs

As **ferramentas de jobs** permitem que um assistente acompanhe o trabalho que o Nodaro faz para ele. Quase toda ferramenta de geração inicia um job e retorna o ID dele na hora; `get_job` e `wait_for_job` informam quando ele termina e onde está o resultado, `list_jobs` lista os seus jobs recentes e `diagnose_run` explica uma falha. As quatro precisam da permissão `jobs:read` e não custam créditos.

## Status dos jobs
| Status | Significado |
| --- | --- |
| `pending`, `queued`, `processing` | O job está aguardando ou em execução. Continue verificando. |
| `pending_review` | O resultado existe, mas a implantação o retém para que uma pessoa o revise. Continue verificando e nunca execute o job de novo. |
| `completed` | O job terminou. `outputUrl` e `outputData` contêm o resultado. |
| `failed` | O job falhou. Leia `retryable` e `guidance`. |
| `cancelled` | O job foi cancelado. |

Um job retido termina como `completed` quando o revisor o aprova, ou como `failed`, com um motivo de política, quando o revisor o rejeita. Um cliente que acompanha o job pela API `tasks` do MCP vê um job retido como `input_required`: a decisão cabe ao revisor, então não peça novos parâmetros ao usuário.

## O envelope do job
`get_job` e `wait_for_job` retornam o mesmo resultado estruturado, o envelope do job. `get_asset` também o retorna, sem `input`.

| Campo | O que contém |
| --- | --- |
| `jobId`, `jobType` | O ID do job e o tipo de job |
| `status`, `progress` | O status acima e o progresso durante a execução |
| `assetKind` | `image`, `video`, `audio` ou null para um resultado de texto ou de dados |
| `outputUrl` | A imagem, o vídeo ou o áudio pronto |
| `outputData` | Saída estruturada, como uma transcrição, um alinhamento ou uma análise |
| `input` | O que foi de fato enviado ao modelo (veja abaixo), ou null |
| `errorMessage` | O erro de um job com falha |
| `credits` | Os créditos do job |
| `createdAt`, `startedAt`, `completedAt` | Marcas de data e hora |
| `retryable`, `guidance`, `suggestedProvider` | Num job com falha, cancelado ou retido: se a mesma requisição pode dar certo, uma frase sobre o que fazer e um modelo alternativo, quando houver |

`input` é um subconjunto seguro da requisição, suficiente para conferir o que o modelo recebeu. Nada fora desta lista é incluído:

- `prompt`, o prompt final, depois de incorporados os seletores, os assuntos e as referências, e `userPrompt`, as suas próprias palavras.
- `negativePrompt` e os IDs dos seletores `direction` e `subject`.
- `provider`, `model`, `duration`, `resolution` e `aspectRatio`.
- `imageUrl`, `endFrameUrl` e as URLs das imagens, vídeos e áudios de referência.
- O `type` do job.

## `get_job`
Retorna um dos seus jobs pelo ID, como envelope do job. Use-a para verificar um job a cada 5 a 10 segundos até ele terminar.

**Permissão:** `jobs:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `job_id` | string | **Obrigatório.** O ID que uma ferramenta de geração retornou. |

**Retorna:** o envelope do job.

## `wait_for_job`
Fica em espera até um dos seus jobs terminar e então retorna o envelope do job. Use-a em vez de um loop de chamadas seguidas a `get_job`.

**Permissão:** `jobs:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `job_id` | string | **Obrigatório.** O job a aguardar. |
| `timeout_s` | integer | Segundos de espera, de 1 a 120. Padrão: `60`. |

**Retorna:** o envelope do job. Quando o job ainda está em execução no fim do prazo, o status é `timeout`. Isso não é um erro: chame `wait_for_job` de novo ou consulte `get_job` periodicamente. Um job retido responde `pending_review` na hora. Para a renderização longa de um vídeo, consultar `get_job` a cada 5 a 10 segundos é melhor do que esperas repetidas.

## `list_jobs`
Lista os seus jobs recentes como dados estruturados: status, tipo, URL da saída, erro, créditos e marcas de data e hora. Use-a para perguntas como “quantas gerações falharam ontem”. Quando o usuário quiser ver os resultados, use [`browse_gallery`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#browse_gallery), que mostra uma grade.

**Permissão:** `jobs:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `kinds` | array | Tipos de mídia a incluir: qualquer combinação de `image`, `video` e `audio`. Padrão: `["image", "video"]`, então o áudio fica de fora, a menos que você o peça. |
| `status` | string | Um destes: `pending`, `queued`, `processing`, `pending_review`, `completed`, `failed`, `cancelled`. |
| `scope` | string | `mine` (padrão) para os seus próprios jobs, ou `public` para resultados públicos recentes de outros usuários. |
| `limit` | integer | De 1 a 200. Padrão: `50`. |
| `cursor` | string | O `next_cursor` da página anterior. |

**Retorna:** uma página de jobs e um `next_cursor` para a página seguinte.

## `diagnose_run`
Explica por que uma execução de workflow ou um job avulso falhou. Informe qualquer um dos dois IDs: a ferramenta tenta primeiro uma execução de workflow e, se não encontrar, um job.

**Permissão:** `jobs:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** Um ID de execução de workflow ou um ID de job. |

**Retorna:** para uma execução de workflow, cada nó com o ID do job, o tipo e o status (`nodes`). Esta é a única ferramenta que relaciona os nós de uma execução aos IDs dos jobs deles. Cada nó com falha também traz a mensagem de erro, o modelo, os créditos efetivamente cobrados (`creditsActual`), uma classe de falha e uma dica de como corrigi-la.

| Classe de falha | Significado |
| --- | --- |
| `content_policy` | Um filtro de segurança bloqueou o prompt ou o resultado |
| `validation` | As configurações ou a entrada não foram aceitas |
| `rate_limited` | A requisição atingiu um limite de taxa |
| `timeout` | A execução demorou demais |
| `post_processing` | O modelo entregou o resultado, mas uma etapa posterior falhou |
| `provider_error` | O serviço do modelo retornou um erro |
| `unknown` | O erro não corresponde a nenhuma das classes acima |

A classe é uma estimativa feita a partir do texto do erro, então trate-a como orientação. Os créditos reservados são reembolsados automaticamente em todas as classes, exceto `post_processing`, porque, nesse caso, o modelo já entregou o trabalho.

## Quando um job falha
1. **Leia `retryable`.** `false` significa que a mesma requisição, sem mudanças, vai falhar de novo. Isso acontece depois de um bloqueio por política de conteúdo ou quando o modelo recusou a combinação de configurações e mídias de entrada.
2. **Siga `suggestedProvider`.** Quando um filtro de segurança bloqueou o resultado e o catálogo tem um modelo alternativo, o job o indica. Execute o mesmo prompt e as mesmas referências nesse modelo, em vez de adivinhar outro.
3. **Mude a requisição quando o modelo a recusar.** Um erro que diz que o modelo rejeitou essas configurações significa que a duração, a proporção, a resolução ou um arquivo de referência não serve para esse modelo. Mude esses valores ou escolha um modelo cuja ficha de recursos em [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) permita a combinação.
4. **Tente de novo nos outros casos.** Um erro temporário do serviço do modelo continua `retryable`, mesmo quando a mensagem parece um problema de validação.

Mais soluções estão em [Solução de problemas](https://nodaro.ai/docs/mcp/troubleshooting).

## Frequently asked questions

### Com que frequência um assistente deve consultar um job do Nodaro?

A cada 5 a 10 segundos com get_job, ou com wait_for_job, que fica em espera por até 120 segundos. Uma imagem costuma ficar pronta em até um minuto, e um vídeo, em 2 a 10 minutos.

### O que significa pending_review?

A implantação revisa os resultados antes de liberá-los, e uma pessoa está revisando este resultado. Não é uma falha. Continue verificando o job e nunca o execute de novo, porque um job duplicado também ficaria retido.

### O que o assistente deve fazer quando um job falha?

Leia os campos retryable e guidance do job. Quando retryable é false, mude as configurações ou a entrada antes de tentar de novo. Quando houver suggestedProvider, execute o mesmo prompt e as mesmas referências nesse modelo.

### As ferramentas de jobs custam créditos?

Não. Elas leem o status de um trabalho que já existe. Só as ferramentas que iniciam jobs gastam créditos.