NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

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étodoCaminhoO que faz
GET/v1/jobs/:id/statusO status enxuto para a consulta periódica: status, progresso, resultado e erro.
GET/v1/jobs/:idA tarefa completa, incluindo o que foi enviado (input_data) e os créditos.
GET/v1/jobsAs 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-statusO status de até 100 tarefas, com os IDs no corpo.
PUT/v1/jobs/:id/ratingAvalia uma das suas tarefas como good ou bad, ou limpa a avaliação.
PATCH/v1/jobs/:idDá um nome a uma das suas tarefas, ou apaga o nome.
POST/v1/jobs/from-uploadRegistra como tarefa uma imagem editada no seu próprio app.
POST/v1/gallery/favoriteFavorita uma tarefa ou remove o favorito.
GET/v1/gallery/favoritesOs IDs das suas tarefas favoritas.
POST/v1/jobs/:id/cancelCancela uma tarefa e libera os créditos reservados para ela.
DELETE/v1/jobs/:idEnvia uma tarefa para a Lixeira. ?forever=true exclui permanentemente uma tarefa que já está na Lixeira.
POST/v1/jobs/:id/restoreTraz de volta da Lixeira uma tarefa excluída.
GET/v1/trashA sua Lixeira: itens removidos de sessões e tarefas excluídas.
GET/v1/component/execute/:jobId/wait-limitQuanto tempo o servidor espera por uma execução de componente.
POST/v1/generate-video-pro/:jobId/stopInterrompe uma execução do Gerar vídeo Pro e mantém os segmentos concluídos.
POST/v1/generate-video-pro/continueContinua uma execução do Gerar vídeo Pro como uma nova tarefa.
POST/v1/credits/video-pro-estimateCalcula 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 --json

GET /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.

CampoSignificado
idO ID da tarefa.
statusEm que ponto a tarefa está. Veja Status das tarefas.
progressDe 0 a 100.
output_dataO 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_messagePor que a tarefa falhou, em palavras.
error_hintUm motivo estruturado para cinco tipos de falha. Veja Por que uma tarefa falhou.
error_detailO que o próprio provedor disse quando a tarefa falhou, ou null. Veja As palavras do próprio provedor.
credit_statusreserved, committed, refunded ou null. Veja Créditos de uma tarefa.
recoveringtrue enquanto a plataforma repara uma tarefa cujo worker parou depois que o modelo já tinha entregado o resultado.
input_dataSó 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.
creditsNa tarefa completa e na lista. Os créditos que a tarefa reservou quando foi aceita. Esse valor nunca muda.
credits_chargedNa 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_releasedNa 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_detailSó 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_idNa tarefa completa e na lista. A sessão de geração em que a tarefa foi arquivada, ou null.
favorited, ratingNa 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.
titleNa 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_atSó na tarefa completa. Carimbos de data e hora.
completed_atQuando 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.

CampoTipoSignificado
width, heightintegerO 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

StatusFinalSignificado
pending, queued, processingNãoA tarefa está aguardando a execução ou em execução.
pending_reviewNãoO resultado existe, e a implantação o retém para uma revisão humana. Continue consultando periodicamente.
completedSimO resultado está em output_data.
failedSimerror_message e error_hint dizem por quê.
cancelledSimVocê 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.runAndWait do SDK consulta periodicamente a cada 2 segundos por até 15 minutos, e o --watch da 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, likeness ou safety. Um bloqueio copyright ou likeness é definitivo: a mesma requisição nunca passa.
  • Em alguns modelos, um filtro safety nem 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. retried informa se essa nova tentativa já aconteceu.
  • suggestedProvider só 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 com class: "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 subject que 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 é request quando a tarefa foi recusada antes de ser executada, e result quando 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, como free_video_limit, instance_cap_reached, budget_exceeded, member_cap_exceeded ou user_allowance_exceeded. Trate um código desconhecido como insufficient_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.

  • null quando 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 em error_hint, nunca nessas palavras.
  • Onde ele aparece: nos mesmos payloads de tarefa que error_message, e na tarefa dentro de um evento de webhook job.failed. Um nó com falha de uma execução de workflow o traz como errorDetail em nodeStates. 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 evento job.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 recebe error_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:

ValorSignificado
reservedOs créditos ficam reservados enquanto a tarefa é executada.
committedA tarefa entregou o resultado e foi cobrada.
refundedA reserva foi liberada, por exemplo, depois de um bloqueio de segurança.
nullA 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_charged pode ser menor que credits. 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 é 0 mais 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, mostra credit_status: "refunded" com credits_charged: 165.
  • credits_charged é null enquanto a reserva da própria tarefa ainda está aberta (credit_status: "reserved"), mesmo quando algumas etapas já foram liquidadas. Também é null quando 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: o credits da própria tarefa mais as reservas das etapas. Para uma tarefa sem etapas, é igual a credits.
  • credits_released é quanto voltou da reserva (credits_held menos credits_charged), depois que todas as reservas da execução foram liquidadas. Até lá, é null.
  • credits e credit_status continuam sendo os da própria tarefa.
  • Se as etapas não puderem ser lidas por um momento, credits_charged, credits_held e credits_released mostram null. 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 consultaSignificado
limitTamanho da página, até 100.
cursorO valor next da página anterior.
statusUm ou mais status de tarefa: pending, queued, processing, pending_review, completed, failed ou cancelled. Um status desconhecido responde 400 validation_error.
typeUma ou mais rotas que criaram a tarefa, como llm-structured ou video-analysis, até 20.
originO app cliente que enviou a tarefa, com o valor exato, como studio.
sourceUma 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.
favoritedtrue mantém as tarefas que você favoritou, e false, as que você não favoritou.
ratinggood, bad, rated (qualquer avaliação) ou unrated.
projectIdAs 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.
inSessionfalse 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.
withSessionstrue acrescenta sessions: [{ id, title, projectId }] a cada tarefa: as sessões em que ela está.
batchIdAs tarefas de um lote do Gerar imagem. Veja Várias imagens em uma chamada.
attachToCharacterIdAs 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: good ou bad.

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étodoCaminhoCorpo ou parâmetrosO 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/favoritesNenhumOs IDs das suas tarefas favoritas, da mais nova para a mais antiga: { data: string[] }.
GET/v1/gallerytype, userId, favoritesOnly=true, limit (de 1 a 50, padrão 20), cursorA 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 favorited e rating em GET /v1/jobs e GET /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 como false: 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 de good, bad ou null responde 400 validation_error.
  • A tarefa privada de outra pessoa responde 404 not_found a um favorito, e nada é guardado. Remover um favorito sempre funciona.
  • Escopos: um token de app OAuth precisa de assets:write para as duas gravações, e de assets:read ou jobs:read para listar os seus favoritos. As leituras de tarefas continuam exigindo jobs:read.
  • Uma implantação que oculta a galeria responde 404 em todas as rotas /v1/gallery.
  • Uma implantação que não permite trabalhos públicos responde a toda visualização de GET /v1/gallery com uma página vazia, { data: [], nextCursor: null, totalCount: 0 }, exceto a sua: o seu próprio userId com o seu token continua listando o seu trabalho. Nela, POST /v1/gallery/favorite só adiciona as suas próprias tarefas, e a tarefa de qualquer outra pessoa responde 404 not_found. Remover um favorito sempre funciona. A rota de denúncia da galeria, POST /v1/gallery/report, responde 404 not_found para 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 responde 404 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 de assets:write.
  • O título volta como title em 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 seu filename.
# 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:

  1. Guarde a imagem editada com POST /v1/upload e anote o assetId dela. Veja Envio de arquivos.
  2. 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 }.
  3. Chame POST /v1/jobs/from-upload com { 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, com thumbnailUrl, width e height. input_data traz type: "image-edit", o assetId e a origem: sourceJobId ou sourceAssetId, mais sourceImageUrl, a imagem da origem. Para uma tarefa que gerou várias imagens, envie a que você editou como sourceImageUrl. 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-edit lista essas tarefas.
  • Um arquivo enviado, uma tarefa. O mesmo assetId de 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 resposta 2xx sempre 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á com POST /v1/sessions/:id/items.
  • Recusas. 404 not_found quando o arquivo, a origem ou a sessão não pertence a você. 400 validation_error quando 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, sourceImageUrl não é uma das imagens dela, as duas origens são enviadas, ou editStateUrl não é uma URL retornada por POST /v1/upload-json. 409 conflict quando você já usou image-edit:<assetId> como Idempotency-Key de outra requisição. 422 job_blocked quando 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/cancel em 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-all e 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-6d2f8b4a7e10

Para 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 com DELETE /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/restore a 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=true exclui 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.

ConsultaSignificado
projectIdUm 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.
toolO 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.
typeO 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 mais budgetExcessMs.
  • budgetExcessMs fica em 0 até a execução iniciar uma renderização longa.
  • pendingBudgetedNodes é true enquanto uma renderização longa ainda não começou e enquanto a própria execução ainda não começou. Por isso, um excesso 0 ainda 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 }
  • fromSegment começ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 fromSegment explí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 --watch

As 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 segmentMode short ou long, a execução primeiro atribui ações completas a trechos da origem, e upperBound: true significa que o valor é o limite da reserva antes do planejamento. A cobrança final segue o plano real.
  • Uma estimativa planOnly cobre a taxa de planejamento e retorna upperBound: false. Os valores sourceSegmentDurations e planCheckpoint dela podem ser enviados de volta como sourceSegmentDurations e seedPlan, 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=.

Última atualização

Nesta página