Tarefas
Verifique, aguarde, liste, avalie e diagnostique tarefas do Nodaro num assistente de IA: envelope, status, tarefas retidas, falhas e modelos alternativos.
As ferramentas de tarefas permitem que um assistente acompanhe o trabalho que o Nodaro faz para ele. Quase toda ferramenta de geração inicia uma tarefa e retorna o ID dela na hora. get_job e wait_for_job informam quando a tarefa termina e onde está o resultado. list_jobs lista e filtra as suas tarefas recentes, rate_job avalia um resultado e diagnose_run explica uma falha. Nenhuma delas custa créditos.
Status das tarefas
| Status | Significado |
|---|---|
pending, queued, processing | A tarefa 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 a tarefa de novo. |
completed | A tarefa terminou. outputUrl e outputData contêm o resultado. |
failed | A tarefa falhou. Leia retryable e guidance. |
cancelled | A tarefa foi cancelada. |
Uma tarefa retida termina como completed quando o revisor a aprova, ou como failed, com um motivo de política, quando o revisor a rejeita. Um cliente que acompanha a tarefa pela API tasks do MCP vê uma tarefa retida como input_required: a decisão cabe ao revisor, então não peça novos parâmetros ao usuário.
O envelope da tarefa
get_job e wait_for_job retornam o mesmo resultado estruturado, o envelope da tarefa. get_asset também o retorna, sem input e sem os dois valores de créditos.
| Campo | O que contém |
|---|---|
jobId, jobType | O ID da tarefa e o tipo de tarefa |
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 |
width, height | O tamanho da saída em pixels, quando a tarefa o registrou. Veja abaixo |
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 uma tarefa com falha |
errorDetail | As palavras do próprio serviço do modelo sobre uma falha, com os links reduzidos ao host e os segredos removidos. null quando ele não deu nenhuma. Mostre ao usuário, mas nunca decida o fluxo com base nele. Veja De quem são as palavras de uma falha |
credits | Os créditos que a própria tarefa reservou quando foi aceita. Esse valor nunca muda |
creditsCharged | Quanto a tarefa custou depois que a reserva dela foi liquidada, incluindo as etapas que ela executou (credits_charged no data da resposta em texto). Veja abaixo |
creditsHeld, creditsReleased | A reserva da execução com as reservas das etapas, e quanto voltou depois que todas as reservas da execução foram liquidadas (credits_held e credits_released). Veja abaixo |
createdAt, startedAt, completedAt | Marcas de data e hora |
retryable, guidance, suggestedProvider | Numa tarefa com falha, cancelada ou retida: se a mesma requisição pode dar certo, uma frase sobre o que fazer e um modelo alternativo, quando houver |
preview | true em uma renderização do Aplicar EDL feita com qualidade de Prévia, em que outputData.quality é "proxy": a montagem privada em 720p para revisão, não a versão final |
creditsCharged pode ser menor que credits. Ele inclui as etapas que a tarefa executou. Algumas tarefas executam outras tarefas para você, como a preparação das referências, a máscara e o vídeo de uma execução do Video Remake. Uma tarefa assim é cobrada por cada etapa quando a etapa é liquidada. Quando a reserva da própria tarefa foi reembolsada, é 0 mais as etapas liquidadas. Por exemplo, uma execução do Video Remake reembolsada, cujas etapas de referência e de máscara foram cobradas, mostra credit_status: "refunded" com creditsCharged: 165. É null enquanto a reserva da própria tarefa ainda está aberta, quando nada na execução foi reservado, ou quando as etapas não puderam ser lidas por um momento. Esse null significa desconhecido, nunca um valor menor.
creditsHeld é a reserva da execução, com as reservas das etapas. creditsReleased é quanto voltou depois que todas as reservas da execução foram liquidadas, e é null até lá. Por exemplo, uma tarefa que reservou 888 créditos e foi liquidada em 444 mostra credits: 888, creditsCharged: 444, creditsHeld: 888 e creditsReleased: 444.
width e height aparecem nas tarefas de imagem concluídas depois que o Nodaro passou a registrar o tamanho, e nas tarefas de Sobreposição em imagem, Sobreposição em vídeo, Máscara de vídeo e Composição por máscara. Numa imagem, eles são o tamanho de outputUrl como armazenado, com a rotação EXIF aplicada. Leia-os para escolher uma proporção para a próxima etapa. Uma tarefa que gerou várias imagens também tem outputData.images, com { url, width, height } para cada imagem.
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, euserPrompt, as suas próprias palavras.negativePrompte os IDs dos seletoresdirectionesubject.provider,model,duration,resolutioneaspectRatio.imageUrl,endFrameUrle as URLs das imagens, vídeos e áudios de referência.- O
typeda tarefa.
get_job
Retorna uma das suas tarefas pelo ID, como envelope da tarefa. Use-a para verificar uma tarefa a cada 5 a 10 segundos até ela 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 da tarefa.
wait_for_job
Fica em espera até uma das suas tarefas terminar e então retorna o envelope da tarefa. 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. A tarefa a aguardar. |
timeout_s | integer | Segundos de espera, no máximo 45. Padrão: 45. Um valor de até 120 é aceito e mesmo assim espera 45 segundos. |
Retorna: o envelope da tarefa. Cada chamada responde em até 45 segundos, porque os clientes de MCP encerram uma chamada de ferramenta pelo próprio relógio, muitas vezes aos 60 segundos. Quando a tarefa ainda está em execução nesse momento, o status é timeout, com progress, jobType, createdAt e startedAt da tarefa. Isso não é um erro: chame wait_for_job de novo com o mesmo job_id. A espera continua de onde parou, e a tarefa não é afetada, então nunca execute a geração de novo. Um vídeo pode levar de 2 a 10 minutos, então conte com várias chamadas, ou consulte get_job a cada 5 a 10 segundos. Uma tarefa retida responde pending_review na hora.
list_jobs
Lista as suas tarefas 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, 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 or array | Só as suas próprias tarefas. Um status ou uma lista de status: pending, queued, processing, pending_review, completed, failed, cancelled. |
types | array | Só as suas próprias tarefas. De 1 a 20 tipos de tarefa, a rota que criou a tarefa, por exemplo generate-image ou llm-structured. |
sources | array | Só as suas próprias tarefas. Uma ou mais superfícies que criaram a tarefa: mcp (um cliente MCP como o Claude ou o ChatGPT), web, cli, sdk, extension, app, api ou internal. |
favorited | boolean | Só as suas próprias tarefas. true mantém as tarefas que você marcou como favoritas, false mantém as demais. |
rating | string | Só as suas próprias tarefas. good, bad, rated (qualquer avaliação) ou unrated. |
project_id | string | Só as suas próprias tarefas. As tarefas que uma sessão deste projeto contém agora, cada uma listada uma vez. none mantém as tarefas que uma sessão sem projeto contém. |
in_session | boolean | Só as suas próprias tarefas. false mantém as tarefas que nenhuma sessão contém, que o app mostra como Geral. true mantém as tarefas que pelo menos uma sessão contém. |
with_sessions | boolean | Só as suas próprias tarefas. Cada tarefa também lista as sessões que a contêm, com o ID, o título e o ID do projeto delas. |
scope | string | mine (padrão) para as suas próprias tarefas, 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 tarefas e um next_cursor para a página seguinte.
O escopo público lista o que a galeria pública mostra, com a mesma moderação de browse_gallery, e nunca traz o ID de outro criador. Nos dois escopos, uma página pode ter menos tarefas que limit e ainda trazer um next_cursor. Continue seguindo-o até que ele seja null.
Em uma implantação que não permite trabalhos públicos (outputs.allowPublic: false), o escopo público não lista nada: { "data": [], "next_cursor": null }.
Nas suas próprias tarefas, os filtros funcionam como em GET /v1/jobs e se combinam com E. types remove o kinds padrão, então uma tarefa sem mídia, como um rascunho llm-structured, aparece na lista. Passe também kinds para manter só as mídias. types, sources, favorited, rating, project_id, in_session e with_sessions são recusados com scope: "public". Uma tarefa excluída nunca aparece na lista: ela está em list_trash.
Cada uma das suas próprias tarefas traz favorited (true ou false) e rating ("good", "bad" ou null). Os dois ficam de fora quando não podem ser lidos por um momento, o que significa desconhecido, e não false. As linhas do escopo público não trazem nenhum dos dois.
Cada uma das suas próprias tarefas traz credits, o valor que a própria tarefa reservou quando foi aceita, que nunca muda, e credits_charged, quanto ela custou depois que a reserva foi liquidada, incluindo as etapas que ela executou. Uma tarefa pode ser liquidada abaixo da reserva dela, e o resto volta para o seu saldo. credits_charged é 0 mais as etapas liquidadas quando a reserva da própria execução foi reembolsada. É null enquanto a reserva da própria tarefa ainda está aberta, quando nada na execução foi reservado, ou quando as etapas não puderam ser lidas por um momento. credits_held é a reserva da execução com as reservas das etapas, e credits_released é quanto voltou depois que todas as reservas da execução foram liquidadas (null até lá). Para totalizar quanto as tarefas custaram, some credits_charged, não credits. As linhas do escopo público não trazem nenhum dos três.
As suas próprias tarefas incluem as suas renderizações do Aplicar EDL, no tipo da saída delas: video para uma montagem e audio para uma mixagem. Uma Prévia traz preview: true. O escopo público nunca lista uma renderização do Aplicar EDL.
rate_job
Avalia uma das suas tarefas como good ou bad, ou apaga a avaliação dela. Uma tarefa tem uma única avaliação, e só o dono dela pode avaliá-la. A tarefa de outra pessoa, ou um ID que não é de uma tarefa, responde “não encontrado”.
Permissão: assets:write. Créditos: grátis.
| Parâmetro | Tipo | Observações |
|---|---|---|
job_id | string | Obrigatório. Uma das suas tarefas. |
rating | string or null | Obrigatório. good ou bad, ou null para apagar a avaliação. |
Retorna: { data: { jobId, rating } }. A avaliação aparece em list_jobs, que pode filtrar por ela, e em GET /v1/jobs.
diagnose_run
Explica por que uma execução de workflow ou uma tarefa avulsa falhou. Informe qualquer um dos dois IDs: a ferramenta tenta primeiro uma execução de workflow e, se não encontrar, uma tarefa.
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 tarefa. |
Retorna: para uma execução de workflow, cada nó com o ID da tarefa, o tipo e o status (nodes). Esta é a única ferramenta que relaciona os nós de uma execução aos IDs das tarefas 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. Ele também traz as palavras do próprio serviço do modelo em providerReason, quando houver e você puder lê-las. Uma execução que falhou e que run_workflow pode continuar também traz resumeHint, a chamada de run_workflow que a continua de onde ela parou. Uma execução de app que falhou traz, em vez disso, a chamada de retry_app_run, como em get_app_run.
De quem são as palavras de uma falha
As palavras do serviço do modelo sobre uma falha pertencem ao dono da tarefa. errorDetail e providerReason ficam de fora, ou são null, nestes casos:
get_assetna tarefa pública de outro usuário, elist_jobscomscope: "public". Nenhum dos dois retorna o ID desse usuário.- Uma tarefa de uma execução de workflow cujo workflow você não pode abrir, como o link de compartilhamento ou o app publicado de outra pessoa que você executou. Isso vale em
get_job,wait_for_job,list_jobs,get_assetediagnose_run. - Uma implantação que reserva essas palavras aos administradores dela. Uma sessão MCP nunca é lida como a de um administrador.
| 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.
Uma execução concluída também informa o seu outcome, "succeeded" ou "nothing_new", como faz get_app_run. Um nó que a execução pulou porque nada chegou à entrada dele traz skipReason: "empty_input". Uma execução que não encontrou nada novo não tem falha a explicar: nada deu errado, e não havia nada a processar.
Quando uma tarefa falha
- Leia
retryable.falsesignifica 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. Uma recusa em que o modelo não deu motivo éretryable: true. - Siga
suggestedProvider. Quando um filtro de segurança bloqueou o resultado e o catálogo tem um modelo alternativo, a tarefa o indica. Execute o mesmo prompt e as mesmas referências nesse modelo, em vez de adivinhar outro. - 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_modelspermita a combinação. Um erro que diz que o modelo não deu motivo pode ser temporário, ou causado pela mídia de entrada, como o tamanho ou o formato dela. Execute de novo uma vez, e mude a mídia de entrada se falhar de novo. - 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.
Perguntas frequentes
Com que frequência um assistente deve consultar uma tarefa do Nodaro?
A cada 5 a 10 segundos com get_job, ou com wait_for_job, que fica em espera por até 45 segundos por chamada. 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 a tarefa e nunca a execute de novo, porque uma tarefa duplicada também ficaria retida.
O que o assistente deve fazer quando uma tarefa falha?
Leia os campos retryable e guidance da tarefa. 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 tarefas custam créditos?
Não. Elas leem o status de um trabalho que já existe. Só as ferramentas que iniciam tarefas gastam créditos.
Páginas relacionadas
Referência das ferramentas MCP
Galeria e mídias
Solução de problemas
Execução de workflows
Última atualização
Referência das ferramentas MCP
Todas as ferramentas do servidor MCP do Nodaro, por finalidade: a permissão de cada uma, como as tarefas informam o resultado e como ler cada ferramenta.
Uploads
Envie suas imagens, áudios e vídeos ao Nodaro de qualquer cliente MCP: com um seletor no chat, um link no navegador ou uma URL pré-assinada via shell.