Tarefas
Consulte status e resultados de tarefas, filtre a sua lista, avalie e favorite resultados, leia o tamanho das imagens, verifique 100 tarefas e cancele tarefas.
Uma tarefa é uma unidade de geração no Nodaro: uma imagem, uma renderização de vídeo, um clipe de fala. A execução de um nó retorna o ID de uma tarefa, e uma execução de workflow cria uma tarefa para cada nó de IA. Os endpoints de tarefas informam o status, o progresso, o resultado e os créditos de cada tarefa. Você consulta uma tarefa periodicamente até ela chegar a completed, failed ou cancelled e, depois, lê o resultado em output_data.
Endpoints
| Método | Caminho | O que faz |
|---|---|---|
GET | /v1/jobs/:id/status | O status enxuto para a consulta periódica: status, progresso, resultado e erro. |
GET | /v1/jobs/:id | A tarefa completa, incluindo o que foi enviado (input_data) e os créditos. |
GET | /v1/jobs | As suas tarefas, das mais recentes para as mais antigas, em páginas. |
GET | /v1/jobs/status?ids=… | O status de até 100 tarefas, com os IDs na query string. |
POST | /v1/jobs/batch-status | O status de até 100 tarefas, com os IDs no corpo. |
PUT | /v1/jobs/:id/rating | Avalia uma das suas tarefas como good ou bad, ou limpa a avaliação. |
PATCH | /v1/jobs/:id | Dá um nome a uma das suas tarefas, ou apaga o nome. |
POST | /v1/jobs/from-upload | Registra como tarefa uma imagem editada no seu próprio app. |
POST | /v1/gallery/favorite | Favorita uma tarefa ou remove o favorito. |
GET | /v1/gallery/favorites | Os IDs das suas tarefas favoritas. |
POST | /v1/jobs/:id/cancel | Cancela uma tarefa e libera os créditos reservados para ela. |
DELETE | /v1/jobs/:id | Envia uma tarefa para a Lixeira. ?forever=true exclui permanentemente uma tarefa que já está na Lixeira. |
POST | /v1/jobs/:id/restore | Traz de volta da Lixeira uma tarefa excluída. |
GET | /v1/trash | A sua Lixeira: itens removidos de sessões e tarefas excluídas. |
GET | /v1/component/execute/:jobId/wait-limit | Quanto tempo o servidor espera por uma execução de componente. |
POST | /v1/generate-video-pro/:jobId/stop | Interrompe uma execução do Gerar vídeo Pro e mantém os segmentos concluídos. |
POST | /v1/generate-video-pro/continue | Continua uma execução do Gerar vídeo Pro como uma nova tarefa. |
POST | /v1/credits/video-pro-estimate | Calcula o preço de uma execução do Gerar vídeo Pro sem iniciá-la. |
Um token OAuth precisa do escopo jobs:read para ler tarefas. Tokens de API pessoais não precisam de escopo. Para que o Nodaro avise o seu servidor quando uma tarefa termina, em vez de consultar periodicamente, registre um endpoint de webhook.
Ler uma tarefa
curl -s https://app.nodaro.ai/v1/jobs/0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10/status \
-H "Authorization: Bearer $NODARO_API_KEY"{
"data": {
"id": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
"status": "completed",
"progress": 100,
"output_data": { "imageUrl": "https://…/0f1a9c2e.png" },
"error_message": null,
"error_hint": null,
"credit_status": "committed"
}
}const { data } = await client.jobs.getStatus(jobId)
if (data.status === 'completed') console.log(data.output_data)
// The full record, with input_data and credits:
const { data: job } = await client.jobs.get(jobId)nodaro jobs get 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10 --jsonGET /v1/jobs/:id/status foi feito para loops de consulta periódica: ele omite input_data e os campos de custo, por isso é mais leve que GET /v1/jobs/:id. Os dois respondem { "data": … }, e os dois respondem 404 para uma tarefa que não existe ou não é sua. Os campos das tarefas usam snake_case, do jeito que o servidor os envia.
| Campo | Significado |
|---|---|
id | O ID da tarefa. |
status | Em que ponto a tarefa está. Veja Status das tarefas. |
progress | De 0 a 100. |
output_data | O resultado. As tarefas de mídia trazem imageUrl, videoUrl ou audioUrl, muitas vezes com thumbnailUrl. As outras tarefas trazem campos próprios, como text ou json. |
error_message | Por que a tarefa falhou, em palavras. |
error_hint | Um motivo estruturado para cinco tipos de falha. Veja Por que uma tarefa falhou. |
error_detail | O que o próprio provedor disse quando a tarefa falhou, ou null. Veja As palavras do próprio provedor. |
credit_status | reserved, committed, refunded ou null. Veja Créditos de uma tarefa. |
recovering | true enquanto a plataforma repara uma tarefa cujo worker parou depois que o modelo já tinha entregado o resultado. |
input_data | Só na tarefa completa. O que foi enviado, depois das correções: por exemplo, o prompt final, o seu próprio userPrompt e os IDs de direction. |
credits | Na tarefa completa e na lista. Os créditos que a tarefa reservou quando foi aceita. Esse valor nunca muda. |
credits_charged | Na tarefa completa e na lista. Quanto a tarefa custou depois que a reserva dela foi liquidada, incluindo as etapas que ela executou, ou null. Veja Créditos de uma tarefa. |
credits_held, credits_released | Na tarefa completa e na lista. A reserva da execução, com as reservas das etapas, e quanto voltou dela depois que todas as reservas foram liquidadas. Veja Créditos de uma tarefa. |
job_type, source, source_detail | Só na tarefa completa. O tipo de tarefa e de onde ela veio: source é internal, mcp, app, cli, sdk, extension, web ou api, e source_detail indica o cliente, como sdk/1.10.0. |
session_id | Na tarefa completa e na lista. A sessão de geração em que a tarefa foi arquivada, ou null. |
favorited, rating | Na tarefa completa e na lista. O seu favorito (true ou false) e a sua avaliação ("good", "bad" ou null). Veja Favoritos e avaliações. |
title | Na tarefa completa e na lista. O nome que você deu à tarefa, ou null até você dar um. Veja Favoritos e avaliações. |
created_at, started_at | Só na tarefa completa. Carimbos de data e hora. |
completed_at | Quando a tarefa terminou, pelo relógio do servidor, ou null até ela terminar. A rota de status também o retorna. |
input_data e output_data são visões públicas: os campos que existem só para o servidor são removidos para todos os chamadores.
O output_data de uma tarefa do Aplicar EDL diz de onde a renderização foi cortada. quality é "proxy" para uma prévia e "final" para uma final, e clipKey indica o clipe do plano quando a requisição enviou um. planBasis volta quando a requisição o enviou, e renderBasis é um carimbo das configurações e das fontes da própria renderização, escrito pelo servidor. Uma tarefa do Visão de falantes devolve os mesmos três carimbos como foram enviados. Uma tarefa mais antiga do Aplicar EDL é lida com a qualidade em que foi pedida.
Uma tarefa de vídeo do Grok Imagine concluída (grok ou grok-i2v) cuja requisição nomeou uma resolução a traz em output_data.recordedResolution, exatamente como a requisição a registrou. Um Grok Extend desse vídeo é cobrado por essa resolução.
Tamanho da imagem nas tarefas de imagem
Toda tarefa cujo output_data tem um imageUrl também traz o tamanho da imagem em pixels: gerações, edições, execuções de imagem para imagem, colagens, sobreposições, quadros extraídos e outras. Um cliente pode montar uma grade antes de as imagens carregarem, ou mostrar e ordenar por tamanho.
| Campo | Tipo | Significado |
|---|---|---|
width, height | integer | O tamanho de imageUrl em pixels, como o arquivo está armazenado: o que você baixa, incluindo a marca d’água do plano gratuito. A orientação EXIF é aplicada, então é o tamanho que um navegador mostra. |
images | { url, width, height }[] | Ao lado de imageUrls, em uma tarefa que criou várias imagens: uma entrada por imagem, na ordem de imageUrls. Uma entrada cujo tamanho não pôde ser lido tem só o url. O próprio imageUrls continua sendo um array de strings. |
{
"imageUrl": "https://cdn.nodaro.ai/images/<jobId>.png",
"imageUrls": ["https://cdn.nodaro.ai/images/<jobId>.png", "https://cdn.nodaro.ai/images/<jobId>-v1.png"],
"width": 1024,
"height": 1536,
"images": [
{ "url": "https://cdn.nodaro.ai/images/<jobId>.png", "width": 1024, "height": 1536 },
{ "url": "https://cdn.nodaro.ai/images/<jobId>-v1.png", "width": 1024, "height": 1536 }
]
}Trate os três campos como opcionais. As tarefas concluídas antes de os tamanhos serem registrados não trazem nenhum deles, e um tamanho que o servidor não conseguiu ler é omitido, nunca adivinhado. Os campos estão em todas as leituras de tarefas: GET /v1/jobs, GET /v1/jobs/:id e GET /v1/jobs/:id/status. As ferramentas de tarefas do MCP get_job, wait_for_job e get_asset trazem width e height ao lado de outputUrl.
Status das tarefas
| Status | Final | Significado |
|---|---|---|
pending, queued, processing | Não | A tarefa está aguardando a execução ou em execução. |
pending_review | Não | O resultado existe, e a implantação o retém para uma revisão humana. Continue consultando periodicamente. |
completed | Sim | O resultado está em output_data. |
failed | Sim | error_message e error_hint dizem por quê. |
cancelled | Sim | Você ou a plataforma cancelou a tarefa. |
Tarefas em recuperação. Quando um worker para depois que o modelo já entregou o resultado, a tarefa fica em processing com recovering: true enquanto a plataforma a repara. Depois, ela é concluída ou reembolsada por conta própria. Em modelos lentos, isso pode levar dezenas de minutos, mais do que a espera padrão do SDK. Um JobTimeoutError de runAndWait não cancela a tarefa, então busque a tarefa de novo mais tarde.
Tarefas retidas para revisão. Em uma implantação que registra uma política de revisão, uma tarefa pode entrar em pending_review. O trabalho está feito, os créditos continuam reserved durante toda a retenção, e uma pessoa decide se o resultado é liberado. A tarefa então termina como completed (aprovada), failed com uma dica policy-block (rejeitada) ou cancelled. Uma tarefa retida pode ser cancelada como qualquer tarefa em andamento. Não envie a requisição de novo, porque uma duplicata também ficaria retida. Quando a implantação define um prazo de revisão, uma tarefa que ninguém revisa a tempo é rejeitada: ela termina como failed, a reserva é reembolsada e o resultado retido é excluído. Uma tarefa retida nunca é aprovada automaticamente. O runAndWait do SDK lança JobHeldError na primeira consulta periódica que encontra pending_review, e o --watch da CLI sai com o código 3.
Boas práticas de consulta periódica
- Consulte periodicamente a cada 2 a 5 segundos. Uma tarefa muda de estado em segundos, não em milissegundos.
- As leituras de status não contam para o limite de taxa do token. Só as execuções e as listagens de workflows contam para o limite por minuto de um token de API pessoal. Veja Limites de taxa.
- Acompanhe muitas tarefas com uma chamada. Use os endpoints em lote em vez de uma requisição por tarefa.
- Deixe o cliente esperar por você. O
client.nodes.runAndWaitdo SDK consulta periodicamente a cada 2 segundos por até 15 minutos, e o--watchda CLI consulta periodicamente até a tarefa terminar.
Por que uma tarefa falhou
A tabela de erros em Erros cobre as requisições que nunca criaram uma tarefa. Uma tarefa que falha depois traz error_message e, em cinco tipos de falha, também um error_hint estruturado.
O filtro de segurança de um modelo bloqueou a requisição:
{ "kind": "safety-block", "class": "safety", "retried": true, "suggestedProvider": "nano-banana-pro" }classécopyright,likenessousafety. Um bloqueiocopyrightoulikenessé definitivo: a mesma requisição nunca passa.- Em alguns modelos, um filtro
safetynem sempre é consistente. No GPT Image 2, no GPT Image 2.5 Flare e no GPT Image 2.5 Sunburst, o Nodaro tenta a mesma requisição de novo uma vez, sem custo extra.retriedinforma se essa nova tentativa já aconteceu. suggestedProvidersó aparece quando o modelo tem uma alternativa recomendada. É um ID de modelo real: envie o mesmo prompt e as mesmas referências para ele.subject: "input_video"aparece quando o provedor recusou o próprio vídeo de entrada da tarefa, e não o prompt, uma imagem de referência ou o resultado. Envie outro clipe.subject: "input_image", sempre comclass: "copyright", aparece quando o provedor recusou uma das imagens de entrada da tarefa por possível violação de direitos autorais. Envie outra imagem: reformular o prompt não vai ajudar.subject: "prompt"aparece, em qualquer classe, quando as próprias palavras do provedor apontaram o prompt. Mudar o prompt é a solução.subject: "audio"aparece, em qualquer classe, quando as próprias palavras do provedor culparam o áudio gerado, e não a imagem.- Trate um
subjectque você não conhece como ausente.
A política de uma implantação rejeitou a tarefa:
{ "kind": "policy-block", "policyId": "brand-safety", "reason": "This image was not approved for release.", "hookPoint": "result" }reasoné um texto escrito para o seu usuário pela política da implantação. Mostre esse texto como está.hookPointérequestquando a tarefa foi recusada antes de ser executada, eresultquando o resultado dela foi rejeitado depois, inclusive por um revisor.- A plataforma não tenta de novo depois de uma rejeição por política e não oferece outro modelo.
Quando a tarefa ficou sem créditos no meio da execução, porque uma etapa que reserva os próprios créditos foi recusada, por exemplo o vídeo que uma execução do Video Remake ou de uma trend inicia:
{ "kind": "credits", "code": "insufficient_credits" }codeé o código da própria recusa, em snake case minúsculo:insufficient_credits, quando o saldo não cobriu a etapa, ou um limite do plano ou do espaço de trabalho, comofree_video_limit,instance_cap_reached,budget_exceeded,member_cap_exceededouuser_allowance_exceeded. Trate um código desconhecido comoinsufficient_credits.- Os créditos da tarefa são reembolsados. Peça à pessoa que faça uma recarga, ou que aumente o limite, e execute de novo. Até lá, a mesma requisição falha do mesmo jeito.
O provedor recusou o vídeo de entrada da tarefa sem indicar uma classe de política de conteúdo. A mensagem fala do arquivo, não de uma política:
{ "kind": "input-refused", "subject": "input_video" }Trate esse caso como qualquer outra falha. Nenhum outro modelo é sugerido, mas você sabe qual entrada mudar: envie outro clipe.
O provedor recusou a requisição como ela foi enviada, indicando um defeito da requisição, como uma configuração, o formato ou o tamanho de um arquivo, ou o comprimento do prompt:
{ "kind": "request-refused", "subject": "input_video" }subject: "input_video" só aparece quando as palavras do provedor apontam o vídeo de entrada como o defeito, por exemplo a duração ou o tamanho dele, ou nenhum personagem encontrado nele. Nesse caso, o que pode mudar é usar outro clipe. A mesma requisição é recusada da mesma forma, então não a execute de novo sem mudanças. Mude as imagens de entrada, o vídeo, o prompt ou as configurações. Não é um bloqueio por política de conteúdo. Em uma tarefa feita de etapas, como uma execução do Video Remake ou de trend, é a recusa de uma etapa.
Nenhuma outra falha tem error_hint. Quando um modelo recusa a própria requisição, porque as configurações ou a mídia de entrada são inválidas para esse modelo, error_message informa isso: mude as configurações ou a mídia antes de executar de novo. Às vezes o modelo recusa a requisição sem motivo, só com a mensagem genérica “Generation failed. Please try again later.” (a geração falhou; tente de novo mais tarde). Então error_message diz que o modelo não deu motivo, e que a causa pode ser temporária ou estar na mídia de entrada, como o tamanho ou o formato dela. Execute essa tarefa de novo uma vez, e mude a mídia de entrada se ela falhar de novo. Um erro do lado do modelo continua valendo uma nova tentativa, seja qual for o texto. error_hint aparece em todo payload de tarefa que traz error_message: a tarefa completa, as rotas de status, a lista e as duas rotas em lote.
As palavras do próprio provedor
Ao lado de error_message, a frase da própria plataforma sobre a falha, uma tarefa que falhou traz error_detail: o que o próprio provedor disse, guardado quando a tarefa falhou. Os links nele são cortados até o host, e os segredos são removidos. Fora isso, as palavras são as do provedor, por exemplo task failed: [400] Request blocked: The uploaded image may contain protected or restricted IP content.
nullquando o provedor não disse nada, por exemplo em uma recusa antes de qualquer envio, em um tempo esgotado ou em uma espera na fila que acabou. Um servidor mais antigo omite o campo.- Mostre-o ao lado de
error_message. Tome decisões com base emerror_hint, nunca nessas palavras. - Onde ele aparece: nos mesmos payloads de tarefa que
error_message, e na tarefa dentro de um evento de webhookjob.failed. Um nó com falha de uma execução de workflow o traz comoerrorDetailemnodeStates. Veja Execuções.
As palavras vão só para quem pode lê-las, porque elas podem citar um prompt:
- Uma execução de tendência esconde as palavras junto com o texto dela, porque elas podem citar a entrada oculta.
- As tarefas de uma execução de workflow só trazem as palavras quando o dono delas pode abrir o workflow que a execução rodou, ou seja, o criador do workflow ou alguém com quem ele foi compartilhado. Você é dono das tarefas de uma execução que inicia pelo link de compartilhamento de outra pessoa, mas elas trazem
error_detail: null, em todo payload de tarefa e no eventojob.failed. - Quem executa um app publicado nunca recebe as palavras.
- A execução oculta de um nó de caso de uso, como o Enxugar episódio, não roda nenhum workflow salvo. Quando um nó de uma execução de workflow a iniciou, ela fica ligada a essa execução e é julgada pelo workflow dessa execução, nos estados dos nós e nas tarefas. Uma execução oculta dentro de outra segue as ligações até a execução de workflow mais próxima. Uma execução oculta iniciada sozinha é do dono dela.
- Uma tarefa sua que não pertence a nenhuma execução, como um nó executado sozinho, traz as palavras dela para você. O mesmo vale para uma tarefa que não está ligada à execução que a iniciou. Isso inclui a tarefa de alguns tipos de nó, uma tarefa da execução oculta de um nó de caso de uso criada antes de essas ligações serem registradas, ou uma tarefa de uma execução cujo workflow foi excluído. Uma execução oculta ligada cuja execução não existe mais esconde as palavras de todos, menos dos administradores.
- Uma implantação pode reservar as palavras aos administradores dela. Com
jobs.errorDetail: "admin"no perfil de superfície, todo chamador que não é administrador recebeerror_detail: null. É assim que aparece uma falha sem palavras do provedor, então um cliente não precisa mudar nada. Veja Edições e perfis de superfície.
Créditos de uma tarefa
credit_status acompanha a reserva de créditos da tarefa:
| Valor | Significado |
|---|---|
reserved | Os créditos ficam reservados enquanto a tarefa é executada. |
committed | A tarefa entregou o resultado e foi cobrada. |
refunded | A reserva foi liberada, por exemplo, depois de um bloqueio de segurança. |
null | A tarefa não tem um registro de créditos para informar. |
Ele aparece em GET /v1/jobs, GET /v1/jobs/:id, GET /v1/jobs/:id/status e GET /v1/jobs/status, nunca em POST /v1/jobs/batch-status. Uma geração que termina em um bloqueio de segurança ou de política é sempre reembolsada. A rara exceção é uma tarefa cujos créditos já tinham sido liquidados antes de uma política rejeitar o resultado dela. Veja Créditos.
O credits de uma tarefa é o valor que a própria tarefa reservou quando foi aceita, e ele nunca muda. GET /v1/jobs e GET /v1/jobs/:id também trazem credits_charged: quanto a tarefa custou depois que a reserva dela foi liquidada, lido do mesmo registro de créditos.
credits_chargedpode ser menor quecredits. Algumas tarefas reservam mais do que usam, por exemplo, para cobrir uma possível nova renderização ou uma duração medida depois da execução. O resto volta para o seu saldo.- Quando a reserva da própria tarefa foi reembolsada,
credits_chargedé0mais as etapas que foram liquidadas. Por exemplo, uma execução do Video Remake reembolsada, cujas etapas de referência e de máscara foram cobradas, mostracredit_status: "refunded"comcredits_charged: 165. credits_chargedénullenquanto a reserva da própria tarefa ainda está aberta (credit_status: "reserved"), mesmo quando algumas etapas já foram liquidadas. Também énullquando nada na execução foi reservado.
Para totalizar quanto as tarefas custaram, some credits_charged, não credits. Por exemplo, uma tarefa que reservou 888 créditos e foi liquidada em 444 mostra credits: 888, credits_charged: 444 e credit_status: "committed".
Tarefas que executam outras tarefas
credits_charged é a cobrança da tarefa como uma execução, com as etapas incluídas. Algumas tarefas executam outras tarefas para você. Por exemplo, uma execução do Video Remake prepara as referências, cria uma máscara e renderiza o vídeo, cada um como uma etapa própria. Uma etapa nunca é listada sozinha, e é cobrada quando é liquidada.
- Uma etapa cuja reserva ainda está aberta ainda não soma nada, e uma etapa reembolsada soma
0. credits_heldé a reserva da execução: ocreditsda própria tarefa mais as reservas das etapas. Para uma tarefa sem etapas, é igual acredits.credits_releasedé quanto voltou da reserva (credits_heldmenoscredits_charged), depois que todas as reservas da execução foram liquidadas. Até lá, énull.creditsecredit_statuscontinuam sendo os da própria tarefa.- Se as etapas não puderem ser lidas por um momento,
credits_charged,credits_heldecredits_releasedmostramnull. Isso significa desconhecido, nunca um valor menor.
Por exemplo, imagine uma prévia do Video Remake cuja reserva própria foi de 44. Ela tem duas etapas de referência de 66, uma máscara de 33 e um vídeo que reservou 3.564 e foi liquidado em 854. Ela mostra credits: 44, credits_charged: 1063, credits_held: 3773 e credits_released: 2710.
Uma execução de workflow conta um nó da mesma forma. Os créditos do nó incluem as etapas liquidadas da tarefa dele, também as de um nó que falhou, e o totalCreditsUsed da execução também. Uma etapa liquidada depois que o nó terminou é contada quando a execução termina.
Listar as suas tarefas
GET /v1/jobs retorna as suas tarefas, das mais recentes para as mais antigas, como { data: Job[], next }. Uma tarefa filha, aquela que outra tarefa iniciou como uma etapa do próprio trabalho, não aparece na lista. As chaves de saída cujo nome começa com __ são só para o servidor, e nenhuma leitura de tarefa as retorna.
| Parâmetro de consulta | Significado |
|---|---|
limit | Tamanho da página, até 100. |
cursor | O valor next da página anterior. |
status | Um ou mais status de tarefa: pending, queued, processing, pending_review, completed, failed ou cancelled. Um status desconhecido responde 400 validation_error. |
type | Uma ou mais rotas que criaram a tarefa, como llm-structured ou video-analysis, até 20. |
origin | O app cliente que enviou a tarefa, com o valor exato, como studio. |
source | Uma ou mais superfícies que criaram a tarefa: mcp, cli, sdk, web, extension, app, api ou internal, o campo source da tarefa. source=mcp lista o que os seus clientes MCP, como o Claude ou o ChatGPT, criaram. |
favorited | true mantém as tarefas que você favoritou, e false, as que você não favoritou. |
rating | good, bad, rated (qualquer avaliação) ou unrated. |
projectId | 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. Não pode ser combinado com inSession=false. |
inSession | false mantém as tarefas que nenhuma sessão contém agora, que o app mostra como Geral. true mantém as tarefas que pelo menos uma sessão contém. |
withSessions | true acrescenta sessions: [{ id, title, projectId }] a cada tarefa: as sessões em que ela está. |
batchId | As tarefas de um lote do Gerar imagem. Veja Várias imagens em uma chamada. |
attachToCharacterId | As tarefas de um personagem. Veja Personagens. |
status, type e source aceitam uma lista separada por vírgulas (status=failed,cancelled) ou um parâmetro repetido (type=a&type=b). Todo filtro corresponde ao valor exato, e os filtros se combinam. Uma página pode ter menos linhas que limit, até nenhuma, e ainda trazer um next: continue paginando enquanto next estiver presente, nunca contando linhas.
const { data: runs, next } = await client.jobs.list({ type: 'llm-structured', origin: 'my-app' })Favoritos e avaliações
Você pode guardar duas marcas nas suas gerações. As duas podem ser lidas em todas as tarefas e usadas como filtros da lista:
- Um favorito é um marcador em uma tarefa: uma das suas, em qualquer status, ou uma tarefa pública concluída de qualquer pessoa na galeria.
- Uma avaliação é o seu veredito sobre uma das suas próprias tarefas:
goodoubad.
Você também pode dar a uma das suas tarefas um título, um nome seu, como “Wedding toast, final” (brinde do casamento, versão final) em uma imagem, um clipe, uma faixa ou uma tentativa de fala.
| Método | Caminho | Corpo ou parâmetros | O que faz |
|---|---|---|---|
PUT | /v1/jobs/:id/rating | { "rating": "good" | "bad" | null } | Avalia uma das suas tarefas, ou limpa a avaliação com null. rating é obrigatório, então limpar é explícito. Retorna { data: { jobId, rating } }. |
PATCH | /v1/jobs/:id | { "title": string | null } | Dá um nome a uma das suas tarefas, ou apaga o nome com null ou "". Retorna { data: { jobId, title } }. |
POST | /v1/gallery/favorite | { "jobId": "..." } | Favorita uma tarefa, ou remove o favorito quando ela já é favorita. Retorna { favorited }, o estado depois da troca. |
GET | /v1/gallery/favorites | Nenhum | Os IDs das suas tarefas favoritas, da mais nova para a mais antiga: { data: string[] }. |
GET | /v1/gallery | type, userId, favoritesOnly=true, limit (de 1 a 50, padrão 20), cursor | A galeria pública, das concluídas mais recentes para as mais antigas. Com o seu próprio userId e o seu token, favoritesOnly=true restringe a lista aos seus favoritos. Cada cartão traz title, o nome que o dono deu à tarefa, ou null. |
- Toda tarefa traz
favoritederatingemGET /v1/jobseGET /v1/jobs/:id. Quando o servidor não consegue lê-los por um momento, as tarefas continuam respondendo e os dois campos são omitidos. Trate um campo ausente como desconhecido, nunca comofalse: uma troca em um favorito desconhecido pode removê-lo. - Uma avaliação por tarefa, a do dono dela. A tarefa de qualquer outra pessoa responde
404 not_found. Uma avaliação diferente degood,badounullresponde400 validation_error. - A tarefa privada de outra pessoa responde
404 not_founda um favorito, e nada é guardado. Remover um favorito sempre funciona. - Escopos: um token de app OAuth precisa de
assets:writepara as duas gravações, e deassets:readoujobs:readpara listar os seus favoritos. As leituras de tarefas continuam exigindojobs:read. - Uma implantação que oculta a galeria responde
404em todas as rotas/v1/gallery. - Uma implantação que não permite trabalhos públicos responde a toda visualização de
GET /v1/gallerycom uma página vazia,{ data: [], nextCursor: null, totalCount: 0 }, exceto a sua: o seu própriouserIdcom o seu token continua listando o seu trabalho. Nela,POST /v1/gallery/favoritesó adiciona as suas próprias tarefas, e a tarefa de qualquer outra pessoa responde404 not_found. Remover um favorito sempre funciona. A rota de denúncia da galeria,POST /v1/gallery/report, responde404 not_foundpara todo item. - Um título é uma linha de texto simples, de 1 a 120 caracteres, em qualquer idioma, sem espaços nas pontas. Qualquer outro valor responde
400 validation_error. Só o dono da tarefa pode dar um nome a ela, e a tarefa de outra pessoa responde404 not_found. Dar um nome é gratuito e funciona em qualquer tipo e status de tarefa, inclusive na Lixeira. Nada mais na tarefa muda. Um token de app OAuth precisa deassets:write. - O título volta como
titleem todo lugar onde a tarefa é retornada:GET /v1/jobs/:id,GET /v1/jobs, os itens de uma sessão,GET /v1/trash, os cartões da galeria (público, ao lado do prompt) e as linhas da biblioteca. Em uma linha da biblioteca,titleé o nome da tarefa que criou o arquivo, não o seufilename.
# Rate a job good, favorite it, then list your good favorites that completed
curl -s -X PUT "https://app.nodaro.ai/v1/jobs/$JOB/rating" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rating": "good"}'
curl -s -X POST "https://app.nodaro.ai/v1/gallery/favorite" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"jobId\": \"$JOB\"}"
curl -s "https://app.nodaro.ai/v1/jobs?rating=good&favorited=true&status=completed" \
-H "Authorization: Bearer $NODARO_API_KEY" | jq '.data[] | {id, favorited, rating}'Registrar uma imagem editada
Uma imagem editada no seu próprio app, por exemplo recortada, anotada ou com filtro, é um arquivo enviado, não uma tarefa. Sozinha, ela não pode ser avaliada, favoritada, arquivada em uma sessão nem passada para uma ferramenta que recebe um ID de tarefa. Registre-a como tarefa:
- Guarde a imagem editada com
POST /v1/uploade anote oassetIddela. Veja Envio de arquivos. - Se quiser, guarde o estado de design do editor com
POST /v1/upload-json, para que a edição possa ser aberta de novo. A rota recebe qualquer corpo JSON de até 25 MB e retorna{ url }. - Chame
POST /v1/jobs/from-uploadcom{ assetId, sourceJobId?, sourceImageUrl?, sourceAssetId?, editStateUrl?, sessionId? }.
A rota registra o arquivo enviado como uma tarefa image-edit concluída na hora e retorna { data: Job }. Ela responde 201 quando registra a imagem, e 200 quando esse assetId já foi registrado antes, com a mesma tarefa.
- Gratuita e privada. Registrar a tarefa não cobra nada, porque o armazenamento do arquivo já foi contado quando você o enviou. A tarefa nunca é pública: ela aparece no seu próprio histórico de tarefas, na sua galeria e nas visualizações da sua biblioteca, nunca na galeria pública.
- O que ela guarda.
output_data.imageUrlé o arquivo enviado, comthumbnailUrl,widtheheight.input_datatraztype: "image-edit", oassetIde a origem:sourceJobIdousourceAssetId, maissourceImageUrl, a imagem da origem. Para uma tarefa que gerou várias imagens, envie a que você editou comosourceImageUrl. A edição de uma imagem de personagem, objeto, criatura ou lugar mantém esse vínculo, então aparece junto com essa entidade.GET /v1/jobs?type=image-editlista essas tarefas. - Um arquivo enviado, uma tarefa. O mesmo
assetIdde novo responde com a mesma tarefa, então uma nova tentativa ou um clique duplo nunca cria duas. Uma nova tentativa também conclui uma tarefa que uma tentativa anterior deixou inacabada, então uma resposta2xxsempre traz uma tarefa concluída. A tarefa mantém a origem, o estado de design e a sessão da requisição que a criou. Os valores próprios de uma nova tentativa não são aplicados. Para mostrar a tarefa em uma segunda sessão, adicione-a lá comPOST /v1/sessions/:id/items. - Recusas.
404 not_foundquando o arquivo, a origem ou a sessão não pertence a você.400 validation_errorquando o arquivo não é uma imagem ou não é um arquivo que você guardou. O mesmo erro aparece quando a tarefa de origem não tem uma imagem finalizada,sourceImageUrlnão é uma das imagens dela, as duas origens são enviadas, oueditStateUrlnão é uma URL retornada porPOST /v1/upload-json.409 conflictquando você já usouimage-edit:<assetId>comoIdempotency-Keyde outra requisição.422 job_blockedquando uma política de tarefas da implantação recusa a imagem, em todas as novas tentativas. - Exclusão. Excluir a tarefa mantém o arquivo entre os seus arquivos enviados. Excluir o arquivo enviado da sua biblioteca mantém o arquivo enquanto esta tarefa ainda o mostra.
Um token de app OAuth precisa de assets:write.
# Record an edited image next to the job it was made from, in a session
curl -s -X POST "https://app.nodaro.ai/v1/jobs/from-upload" \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"assetId\": \"$ASSET\", \"sourceJobId\": \"$JOB\", \"sessionId\": \"$SESSION\"}" | jq '.data | {id, status, output_data}'Consultar periodicamente muitas tarefas de uma vez
Dois endpoints retornam o status de até 100 tarefas em uma única ida e volta:
curl -s "https://app.nodaro.ai/v1/jobs/status?ids=$JOB_A,$JOB_B,$JOB_C" \
-H "Authorization: Bearer $NODARO_API_KEY"{
"jobs": [
{ "id": "0f1a9c2e-…", "status": "completed", "output_data": { "imageUrl": "https://…/a.png" }, "error_message": null, "error_hint": null, "credit_status": "committed" },
{ "id": "7d3e5f60-…", "status": "processing", "output_data": null, "error_message": null, "error_hint": null, "credit_status": "reserved" }
]
}curl -s -X POST https://app.nodaro.ai/v1/jobs/batch-status \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"jobIds\": [\"$JOB_A\", \"$JOB_B\", \"$JOB_C\"]}"A resposta é { "data": [ … ] }, com id, status, output_data, error_message e error_hint para cada tarefa, e sem credit_status.
Os IDs que não existem, ou que pertencem a outra pessoa, ficam de fora sem erro. Compare a resposta com a sua própria lista de IDs.
Cancelar ou excluir uma tarefa
POST /v1/jobs/:id/cancel cancela uma tarefa e libera os créditos que ela reservou. A resposta é { "success": true, "cancelled": 1 }. Uma tarefa retida em pending_review também pode ser cancelada. Cancelar uma tarefa também cancela as tarefas filhas dela que ainda estão em execução. Uma tarefa filha concluída fica como está, e uma que já foi enviada ao modelo termina, como qualquer tarefa em andamento.
Cancelar uma tarefa de LLM medida. Uma tarefa de modelo de linguagem é cobrada pelos tokens que a chamada dela usa, então o cancelamento depende de a chamada já ter começado:
POST /v1/jobs/:id/cancelem uma tarefa cuja chamada já começou responde{ "success": true, "cancelled": 0, "inFlight": true }. A tarefa termina e é cobrada só pelos créditos que usou.- O Parar do canvas,
POST /v1/jobs/cancel-alle o cancelamento de um workflow (POST /v1/workflow-executions/:id/cancel) cancelam a tarefa. Ela é cobrada pelo que o provedor já cobrou por ela, e o resto da reserva é reembolsado. - Uma tarefa parada antes de a chamada começar é reembolsada, seja qual for a forma de cancelamento. A exceção é o que uma tentativa anterior da mesma tarefa já usou, por exemplo uma nova tentativa depois de uma tentativa cobrada. Esse uso é cobrado.
DELETE /v1/jobs/:id envia uma tarefa para a Lixeira e responde { "success": true }. Só o dono da tarefa pode excluí-la. Uma tarefa que ainda está em execução continua em execução, então cancele-a antes quando o trabalho dela precisar parar. Nada é reembolsado quando uma tarefa é excluída. Os apps OAuth precisam do escopo assets:write para excluir ou restaurar uma tarefa.
curl -s -X POST https://app.nodaro.ai/v1/jobs/$JOB_ID/cancel \
-H "Authorization: Bearer $NODARO_API_KEY"const { cancelled } = await client.jobs.cancel(jobId)
await client.jobs.delete(jobId)nodaro jobs cancel 0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10Para interromper uma execução de workflow inteira, cancele essa execução: veja Execuções.
A Lixeira
Remover um item de uma sessão e excluir uma tarefa enviam esse item ou essa tarefa para a Lixeira.
- Um item removido fica lá até você restaurá-lo com
POST /v1/sessions/:id/items/:jobId/restore, ou excluí-lo permanentemente comDELETE /v1/sessions/:id/items/:jobId?forever=true. Uma remoção nunca exclui a tarefa. Um item que não está em nenhuma sessão ativa aparece em Geral. - Uma tarefa excluída some de todas as leituras: listas de tarefas e leituras por ID, consultas de status, a galeria, os feeds e as prévias das sessões, as ferramentas MCP e a CLI. Ela pode ser restaurada por 30 dias.
POST /v1/jobs/:id/restorea coloca de volta em todas as sessões em que ela estava. - Depois de 30 dias, uma tarefa excluída é excluída permanentemente, com a mídia privada dela. Uma cópia salva na Biblioteca continua lá.
- Excluir permanentemente agora.
DELETE /v1/jobs/:id?forever=trueexclui permanentemente uma tarefa que já está na Lixeira. Em uma tarefa ativa, a resposta é409 not_in_trash. - Nada é reembolsado quando uma tarefa é excluída, nem quando ela é excluída permanentemente.
GET /v1/trash lista a Lixeira, da entrada mais recente para a mais antiga, uma página por vez (limit de 1 a 100, padrão 50, e cursor). Cada entrada é { kind: "removed", removedAt, session: { id, title, projectId }, job } ou { kind: "deleted", deletedAt, purgeAt, job }. Um item removido cuja tarefa você também excluiu aparece uma só vez, como a tarefa excluída.
| Consulta | Significado |
|---|---|
projectId | Um ID de projeto: os itens removidos das sessões desse projeto e as tarefas excluídas que uma sessão dele continha. none: as sessões sem projeto e Geral. |
tool | O que uma sessão daquela ferramenta de criação contém ou continha. Uma tarefa que nunca esteve em uma sessão não tem ferramenta, então tool a deixa de fora. |
type | O input_data.type da tarefa, separado por vírgulas. Filtre só por type, com os tipos de tarefa da sua ferramenta, para incluir tarefas excluídas que nunca estiveram em uma sessão. |
Excluir uma sessão também exclui os itens removidos dela.
Execuções de componentes
POST /v1/component/execute executa um Componente salvo em segundo plano e responde 202 com { jobId }. Consulte essa tarefa periodicamente, como qualquer outra. Em uma implantação que não permite trabalho público, ela só executa os seus próprios componentes, ou um componente dentro de uma execução completa de um workflow que o contém. Qualquer outra chamada responde 404 not_found “Component not found”. Com um token de app OAuth, a rota precisa do escopo workflows:execute, e a leitura do limite de espera abaixo precisa de jobs:read. O servidor dá 90 minutos a uma execução de componente, mais o orçamento de tempo de qualquer renderização longa dentro dela, como a renderização final de um nó Aplicar EDL.
Um cliente com um limite de tempo próprio pode perguntar quanto tempo o servidor vai esperar:
curl -s https://app.nodaro.ai/v1/component/execute/$JOB_ID/wait-limit \
-H "Authorization: Bearer $NODARO_API_KEY"{ "data": { "budgetExcessMs": 0, "waitLimitMs": 5400000, "pendingBudgetedNodes": true } }waitLimitMsé a espera do servidor para esta execução: 90 minutos maisbudgetExcessMs.budgetExcessMsfica em0até a execução iniciar uma renderização longa.pendingBudgetedNodesétrueenquanto uma renderização longa ainda não começou e enquanto a própria execução ainda não começou. Por isso, um excesso0ainda não significa que não há nada longo dentro dela.
Os dois valores podem mudar durante a execução, então pergunte de novo quando waitLimitMs for atingido. A rota só responde ao dono da execução, com 404 para qualquer outra pessoa e para tarefas que não são execuções de componentes. O próprio editor usa esta regra: espera 30 minutos por uma execução sem nada longo dentro, waitLimitMs depois que uma renderização longa começa e pelo menos 90 minutos enquanto pendingBudgetedNodes é true. Depois, pergunta de novo.
Execuções do Gerar vídeo Pro
O Gerar vídeo Pro faz vídeos longos um segmento por vez e salva o progresso entre os segmentos, então uma execução pode ser interrompida e continuada depois. Ele roda no Nodaro Cloud, e uma instalação auto-hospedada o executa pela conexão com o Nodaro Cloud.
Interromper uma execução
POST /v1/generate-video-pro/:jobId/stop interrompe de forma controlada uma execução em processing:
- O segmento que está sendo gerado é abandonado e, mesmo assim, é cobrado, porque o modelo continua a renderizá-lo.
- Os segmentos restantes são pulados.
- Todos os segmentos concluídos são unidos no vídeo final da tarefa.
- A parte não usada da reserva é reembolsada.
A resposta é { "jobId": "…", "stopping": true }. Continue consultando a tarefa periodicamente: ela termina como completed, com output_data.pro.stopped igual a true e com stoppedAtSegment. Já uma tarefa que ainda está em pending é cancelada com reembolso total.
Continuar uma execução
POST /v1/generate-video-pro/continue inicia uma nova tarefa a partir de uma tarefa terminada. Ele reaproveita o plano da tarefa original e todos os segmentos entregues antes de fromSegment, e gera de novo a partir dali:
{ "fromJobId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "fromSegment": 4 }fromSegmentcomeça em 1. Por padrão, é o primeiro segmento que não foi entregue.- A tarefa original precisa estar terminada: interrompida, com falha e pelo menos um segmento entregue, ou concluída. Um
fromSegmentexplícito em uma execução concluída gera o final dela de novo. - Você paga só pelos segmentos gerados de novo, mais a taxa fixa do Gerar vídeo Pro.
- A rota respeita o cabeçalho
Idempotency-Key, então uma requisição repetida não inicia uma segunda tarefa.
A resposta é { jobId, continuedFromJobId, fromSegment, segmentCount }. Consulte periodicamente o novo jobId.
curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/$JOB_ID/stop \
-H "Authorization: Bearer $NODARO_API_KEY"
curl -s -X POST https://app.nodaro.ai/v1/generate-video-pro/continue \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4c1f0a7e-2b3d-4e5f-8a9b-0c1d2e3f4a5b" \
-d "{\"fromJobId\": \"$JOB_ID\", \"fromSegment\": 4}"await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // completes with a partial video
const { jobId: childId } = await client.videoPro.continueRun(jobId, { fromSegment: 4 })nodaro video-pro stop 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
nodaro video-pro continue 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d --from-segment 4 --watchAs duas rotas respondem 404 para uma tarefa que não é sua e 400 para uma tarefa que não é uma execução do Gerar vídeo Pro.
Estimar uma execução
POST /v1/credits/video-pro-estimate calcula o preço de uma execução do Gerar vídeo Pro sem criar uma tarefa nem reservar créditos:
{ "provider": "gemini-omni-flash", "resolution": "720p", "duration": 12, "renderMethod": "keyframes", "segmentMode": "short" }Em uma configuração de exemplo, a resposta é { "data": { "credits": 760, "upperBound": true } }. Leia a resposta em tempo real para ver os preços atuais.
Propriedade
Tipo
- Com
segmentModeshortoulong, a execução primeiro atribui ações completas a trechos da origem, eupperBound: truesignifica que o valor é o limite da reserva antes do planejamento. A cobrança final segue o plano real. - Uma estimativa
planOnlycobre a taxa de planejamento e retornaupperBound: false. Os valoressourceSegmentDurationseplanCheckpointdela podem ser enviados de volta comosourceSegmentDurationseseedPlan, com o mesmo modo e as mesmas configurações.
Leia Gerar vídeo Pro para saber como a segmentação funciona e o que cada configuração faz.
Perguntas frequentes
O que é uma tarefa na API do Nodaro?
Uma tarefa é uma unidade de geração, como uma imagem, uma renderização de vídeo ou um clipe de fala. POST /v1/<node-type> retorna o ID de uma tarefa, e uma execução de workflow cria uma tarefa para cada nó de IA que executa.
Com que frequência devo consultar periodicamente uma tarefa do Nodaro?
A cada 2 a 5 segundos. Uma tarefa muda de estado em segundos, não em milissegundos. Para acompanhar muitas tarefas, use GET /v1/jobs/status ou POST /v1/jobs/batch-status, que retornam até 100 tarefas em uma chamada.
O que significa o status pending_review?
A implantação retém o resultado para uma revisão humana antes de liberá-lo. A tarefa continua em andamento, e os créditos dela continuam reservados. Continue consultando periodicamente: ela termina como completed, failed ou cancelled.
Como sei se uma tarefa com falha foi reembolsada?
Leia credit_status em GET /v1/jobs/:id ou GET /v1/jobs/:id/status. O valor é reserved, committed ou refunded. Uma geração bloqueada por um filtro de segurança ou por uma política da implantação é sempre reembolsada.
Como sei quanto uma tarefa realmente custou?
Leia credits_charged em GET /v1/jobs ou GET /v1/jobs/:id. É quanto a tarefa custou depois que a reserva dela foi liquidada, incluindo as etapas que ela executou, e pode ser menor que a reserva. É null enquanto a reserva da própria tarefa ainda está aberta.
Posso avaliar ou favoritar uma tarefa pela API?
Sim. PUT /v1/jobs/:id/rating define good, bad ou null em uma das suas tarefas, e POST /v1/gallery/favorite marca ou desmarca um favorito. GET /v1/jobs filtra pelos dois com rating= e favorited=.
Páginas relacionadas
Nós
Execuções
Erros
Créditos
Gerar vídeo Pro
Última atualização
Nós
Execute qualquer nó do Nodaro com POST /v1/<node-type>, descubra nós, modelos e valores de seletores e guie o prompt com referências e IDs de direção.
Execuções
Acompanhe uma execução de workflow nó a nó, leia o resultado de cada nó, liste execuções passadas e cancele agora ou quando os nós em andamento terminarem.