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

Workflows

Execute workflows do Nodaro pela API com novas entradas, aguarde ou consulte periodicamente o resultado; liste, crie, atualize, exporte e mova workflows.

Um workflow é um canvas salvo de nós conectados. A API pode executá-lo, passar novos valores de entrada para uma única execução e gerenciá-lo como qualquer outro recurso. Uma execução começa com uma requisição que retorna um executionId, e você consulta a execução periodicamente até ela terminar. Uma execução curta também pode aguardar o resultado na mesma requisição.

Endpoints

Executar um workflow

MétodoCaminhoO que faz
POST/v1/workflows/:id/runExecuta o workflow salvo, ou alguns dos nós dele. Responde 202 com um executionId.
POST/v1/workflows/:id/render-final/estimateCota uma Renderização final: os nós que ela executa e os créditos dela. Não cria nem cobra nada.
GET/v1/api/workflowsLista os workflows que o seu token de API pode executar. Aceita ?limit= e ?cursor=.
GET/v1/api/schema?workflowId=…Os campos de entrada e as saídas de um workflow, com estimatedCredits.
POST/v1/api/runExecuta um workflow com novos valores de entrada. Adicione ?wait=true&timeout=… para aguardar o resultado.
GET/v1/api/status/:execIdO status da execução, as contagens de nós, os créditos usados e, depois que ela foi concluída, o outcome dela.
GET/v1/api/result/:execIdAs saídas da execução, quando o status dela for completed ou failed.
POST/v1/app/:slug/runExecuta um app publicado com os campos do formulário dele. Veja Miniapps.

Gerenciar workflows

MétodoCaminhoO que faz
GET/v1/projects/:projectId/workflowsOs workflows de um projeto, sem os nós e as conexões.
GET/v1/workflowsOs seus workflows de todos os projetos.
GET/v1/workflows/:idUm workflow com os nós, as conexões e as configurações dele.
POST/v1/projects/:projectId/workflowsCria um workflow em um projeto.
PATCH/v1/workflows/:idAltera qualquer subconjunto dos campos de um workflow.
DELETE/v1/workflows/:idExclui um workflow.
GET/v1/workflows/:id/exportExporta o workflow como um pacote JSON. Adicione ?assets=true para incluir os personagens, objetos e locais dele.
POST/v1/workflows/importCria um workflow a partir de um pacote.
POST/v1/workflows/:id/moveMove um workflow para outro projeto.
GET/v1/workflows/shared-with-meOs workflows que outras pessoas compartilharam com você.
GET/v1/mcp-conversationsAs suas conversas MCP de um mês. Veja Conversas MCP.

O compartilhamento, os colaboradores e as permissões por workflow estão em Espaços de trabalho e organizações.

Três formas de executar um workflow

EndpointCredencialValores de entradaUse quando
POST /v1/workflows/:id/runQualquer token. Tokens OAuth precisam de workflows:execute.Os valores salvos. nodeIds executa um subconjunto.Você executa o workflow como ele está salvo, para a sua conta ou para um usuário OAuth.
POST /v1/api/runUm token de API pessoalinputs substitui os valores dos nós de entrada nesta execução.Um script precisa de valores diferentes a cada execução, ou quer aguardar o resultado.
POST /v1/app/:slug/runQualquer tokenOs campos do formulário do app, mais substituições diretas de campos de nósO workflow está publicado como um app com um formulário com curadoria.

Os cinco endpoints /v1/api/ são a via original dos tokens de API. Eles existem desde antes dos apps publicados e continuam com suporte, mas as novas integrações que precisam de entradas costumam publicar o workflow como app e usar POST /v1/app/:slug/run. Essa rota recebe os campos do app como um mapa plano em inputs e um objeto opcional inputOverrides, com substituições diretas no formato { nodeId: { field: value } }. Os dois são mesclados, e inputOverrides prevalece em qualquer campo que ambos definam. Uma entrada plana cujo campo é um número, como um controle deslizante exposto, aceita um número ou um texto numérico: "0.4" chega ao nó como 0.4. Um valor que não é número é repassado sem mudança, e o nó o trata como sempre tratou.

Executar um workflow salvo

POST /v1/workflows/:id/run inicia uma execução do workflow como ele está salvo. Envie um corpo vazio para executar todos os nós, ou nodeIds para executar um subconjunto:

curl -s -X POST https://app.nodaro.ai/v1/workflows/8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f/run \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
{ "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending" }
const { executionId } = await client.workflows.run(workflowId)

// Or run only some nodes:
await client.workflows.run(workflowId, { nodeIds: ['text-prompt-1', 'generate-image-1'] })
nodaro workflows run 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f --watch
nodaro workflows run 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f --node text-prompt-1 generate-image-1

Propriedade

Tipo

A resposta é 202 Accepted com { executionId, status }, em que status é pending ou running. Consulte a execução periodicamente com GET /v1/workflow-executions/:id, descrito em Execuções. Com --watch, a CLI faz a consulta periódica por você e sai com o código 2 quando a execução falha e 130 quando ela é cancelada.

StatusCódigoSignificado
402insufficient_creditsUma continuação ou uma Renderização final que seus créditos não cobrem. Nada foi criado.
403forbiddenVocê pode ver o workflow, mas não pode executá-lo. Em um espaço de trabalho, para executar é preciso ter acesso de edição e ser um membro ativo.
404not_foundO workflow não existe, ou você não pode vê-lo.
409already_runningO workflow já tem uma execução ativa. A resposta traz o executionId dessa execução.

Uma execução comum não confere seu saldo antes de começar. Quando seus créditos não cobrem um nó, esse nó falha com um erro de créditos insuficientes, e a execução informa a falha.

Continuar uma execução

POST /v1/workflows/:id/run pode continuar uma execução anterior em vez de começar do zero. Envie continueFromExecutionId com o id dessa execução, junto com nodeIds. A execução roda só os nodeIds. Cada um dos outros nós repassa o que a execução anterior produziu, como essa execução registrou, e nunca os resultados salvos do workflow. As entradas que essa execução usou, como um upload ou uma entrada de app, são usadas de novo, e nada antes dos nodeIds é executado ou cobrado de novo.

  • Um nó que a execução anterior também não executou repassa os resultados salvos dele, como fez naquela execução.
  • Um Plano de edição repassa o plano que a execução anterior fez, com a sua revisão atual aplicada. Uma revisão feita sobre outro plano é ignorada.
  • Um nó que a execução anterior não concluiu não repassa nada e não é executado de novo. Um nó cujas entradas vêm todas desses nós é pulado, junto com os nós depois dele.
  • Os inputOverrides da execução anterior são aplicados de novo. Os inputOverrides que você envia são aplicados por cima deles, campo a campo, e os seus prevalecem.

Uma Renderização final escrita à mão é um exemplo. Ela executa a renderização e todos os nós depois dela, com a renderização em Final somente nesta execução:

{
  "nodeIds": ["<render node id>", "<every node after it>"],
  "inputOverrides": { "<render node id>": { "quality": "final" } },
  "continueFromExecutionId": "<a completed run whose render made a Preview>"
}

A execução anterior precisa ser uma execução que você iniciou, deste próprio workflow e não de uma versão de app publicado, e precisa ter terminado como completed. Caso contrário, a requisição é recusada antes de existir qualquer execução:

StatusCódigoSignificado
400continuation_subset_requirednodeIds está ausente ou vazio, sem continueMode.
400continuation_workflow_mismatchA execução anterior executou outro workflow.
400continuation_version_mismatchA execução anterior executou uma versão de app publicado do workflow. Continue uma execução de app que falhou com o Tentar novamente do app.
400validation_errorcontinueFromExecutionId não é um id de execução.
404continuation_not_foundA execução não existe, ou não é sua.
409continuation_not_completedA execução anterior ainda está em andamento, falhou ou foi cancelada.

Continuar uma execução que falhou

Uma execução de um workflow salvo que falhou pode ser continuada de onde parou, mantendo o que ela concluiu. Envie continueFromExecutionId com o id da execução que falhou e "continueMode": "from-failed":

{
  "continueFromExecutionId": "<the run that failed>",
  "continueMode": "from-failed"
}
  • Só o que falta é executado. Cada nó que a execução que falhou concluiu repassa o resultado, e não é executado nem cobrado de novo. Um nó que falhou é executado de novo por inteiro, com todos os itens da lista.
  • Os nós considerados. nodeIds é opcional. Sem ele, a execução é continuada nos nós em que foi iniciada: uma execução de nós indicados, nesses nós; uma execução completa, em todos os nós. Uma continuação de uma continuação mantém os nós da primeira execução. Cada nó que ficou com falha ou foi segurado é adicionado a eles, com o que esses nós precisam antes deles.
  • Todo nó que você indica conta. Com nodeIds, um nó que nenhuma execução da cadeia executou conta como pendente, então ele é executado e cobrado. Por isso, indicar todos os nós também executa cada nó de trabalho que todas as execuções da cadeia deixaram de fora. Um nó que foi executado em qualquer execução da cadeia nunca é executado de novo por ser indicado.
  • Nós que nunca são executados. Uma fonte ou um upload, um gatilho, um seletor, ou um contêiner Grupo ou Coletar repassa o que a execução repassou. Um nó definido para ser pulado, no workflow ou pelos inputOverrides da execução, nunca é executado. Indicar só nós assim não deixa nada para executar.
  • Cadeias com continuações antigas. Uma continuação executada antes desta regra existir registrou um nó assim como concluído. Nessa cadeia, indicar o nó ainda o conta como feito, então ele não é executado. Para executá-lo, continue a execução mais recente da cadeia só com nodeIds, sem continueMode. Isso só funciona quando essa execução foi concluída. Quando ela falhou, primeiro continue a partir da falha sem esse nó.
  • A continuação mais recente decide. Uma continuação guarda tudo o que as execuções antes dela concluíram, então o servidor sempre parte da continuação mais recente da execução. Quando essa continuação falhou, a requisição é recusada com continuation_superseded, que a indica: continue essa. Quando ela já executou tudo o que faltava, o mesmo código diz que o trabalho está feito. Quando ela concluiu só parte do que faltava, a execução parte dela. A resposta 202 indica em continuedFrom a execução da qual continuou.
  • Uma continuação que parou em uma prévia. Continuar de novo pararia na mesma prévia, então a requisição é recusada com continuation_preview_pending. A resposta indica essa continuação em executionId, as renderizações dela em renderNodeIds e os nós Enxugar episódio dela em reviewNodeIds. O campo next dela é a execução que os conclui: envie next como corpo de POST /v1/workflows/:id/run.
  • O saldo é conferido antes. Uma continuação que seus créditos não cobrem é recusada com 402 insufficient_credits antes de começar. O preço dela é calculado sobre o que ela ainda executa. Um nó que a execução que falhou concluiu nunca é cobrado. Um nó que você indica e que nenhuma execução da cadeia executou é cobrado, porque ele é executado.
  • Envie um cabeçalho Idempotency-Key. Duas continuações enviadas no mesmo momento podem começar as duas. Com a mesma chave, uma nova tentativa da requisição responde com a execução que ela já iniciou, com "deduped": true.

Uma continuação de onde falhou é recusada com estes códigos, além dos de cima:

StatusCódigoSignificado
409continuation_not_failedA execução não falhou.
409continuation_supersededUma continuação mais recente da execução falhou (continue essa), ou concluiu tudo o que faltava. Ela é indicada em executionId e em supersededBy: { executionId, status }.
409continuation_preview_pendingA continuação mais recente parou em uma prévia. Envie o next dela antes.
409continuation_subset_requiredNão sobrou nada a continuar, ou nenhum dos nós em que a primeira execução foi iniciada ainda está no workflow. Indique os nós com nodeIds, ou inicie uma nova execução.
409already_runningUma execução deste workflow, inclusive uma continuação, ainda está em andamento. O executionId dela está na resposta.

Uma execução de um app publicado não é continuada aqui: use o Tentar novamente do app. No editor, a mesma continuação é Continuar de onde falhou, descrito em Execução de workflows.

Renderização final

Em vez de listar os nós você mesmo, indique a renderização e deixe o servidor calcular o resto. Envie renderFinal com o id do nó da renderização e continueFromExecutionId, sem nodeIds nem inputOverrides. O servidor executa o que a Renderização final executa no editor: a renderização do Aplicar EDL em Final somente nesta execução, e depois todos os nós após ela. Quando um Troca de câmeras fica entre o Plano de edição e a renderização, o Troca de câmeras é executado de novo antes. O Plano de edição não é executado de novo. A execução passa a ser uma continuação, com as mesmas verificações.

{
  "renderFinal": { "renderNodeId": "<render node id>" },
  "continueFromExecutionId": "<a completed run whose render made a Preview>"
}

Peça uma cotação antes com POST /v1/workflows/:id/render-final/estimate e o corpo { renderNodeId, continueFromExecutionId }. A cotação não cria nem cobra nada. Ela responde 200 com { data: { renderNodeId, nodeIds, inputOverrides, estimatedCredits, holdCredits, sufficient, available } }:

  • nodeIds e inputOverrides são os nós que a execução roda e a substituição com que ela roda, { "<render node id>": { "quality": "final" } }.
  • estimatedCredits é o preço dos nós que a execução roda, com a renderização em Final. Quando a execução roda um nó de LLM, a resposta acrescenta estimatedCreditsIsEstimate: true: esse nó é cobrado pelo uso real, então mostre o valor como ≈N.
  • holdCredits é o que a execução reserva enquanto renderiza. Um clipe UGC é reservado por cerca do dobro do preço dele, e a parte não usada volta quando ele termina. holdCredits nunca é menor que estimatedCredits.
  • sufficient diz se os seus créditos cobrem essa reserva, e available é o seu saldo de créditos disponível. available é null quando quem paga é o orçamento de um espaço de trabalho ou a conta de cobrança de uma implantação.
  • Os três valores são null em uma edição sem créditos.

A cotação recusa com os códigos de continuação acima. As duas rotas também recusam com estes códigos:

StatusCódigoSignificado
400render_final_node_not_foundO workflow não tem nenhum nó com esse id.
400render_final_not_a_renderO nó não é uma renderização do Aplicar EDL.
400validation_errorrenderFinal foi enviado com nodeIds ou inputOverrides, ou sem continueFromExecutionId.

Uma Renderização final confere o seu saldo antes de começar, com o holdCredits da cotação. Uma execução que você não consegue cobrir responde 402 insufficient_credits com required, que é essa reserva, e available, e nenhuma execução é criada. A verificação cobre só o saldo. Um modelo que o seu plano não pode usar, ou um limite diário, continua sendo recusado por aquele nó quando a execução chega a ele.

Executar um workflow com novos valores de entrada

POST /v1/api/run recebe um objeto inputs que substitui os valores dos nós de entrada somente nesta execução. A autenticação é feita com um token de API pessoal. As chaves de inputs são ids de nós ou, por conveniência, rótulos únicos de nós. Dentro de cada chave, informe o campo de entrada do nó, como text para um prompt de texto.

promptTextotext-prompt-1Gerar imagemgenerate-image-1
O workflow de exemplo: um nó Texto, cujo texto a execução pela API substitui, alimenta um nó Gerar imagem.

O exemplo abaixo executa um workflow com um nó Texto, de id text-prompt-1, conectado a um nó Gerar imagem.

Encontrar os campos de entrada

GET /v1/api/schema lista as entradas do workflow, com o campo que cada uma recebe, as saídas e uma estimativa dos créditos que uma execução custa:

curl -s "https://app.nodaro.ai/v1/api/schema?workflowId=$WORKFLOW_ID" \
  -H "Authorization: Bearer $NODARO_API_KEY"
{
  "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
  "name": "Sunset stills",
  "estimatedCredits": 50,
  "inputs": [
    { "nodeId": "text-prompt-1", "key": "text", "label": "Prompt", "type": "text" }
  ],
  "outputs": [
    { "nodeId": "generate-image-1", "label": "Generate Image", "type": "image" }
  ]
}

Quando o workflow tem um nó de LLM medido, a resposta acrescenta estimatedCreditsIsEstimate: true, e estimatedCredits é uma estimativa: mostre-o como ≈N. Um workflow que indica um modelo de LLM ainda sem preço continua sendo descrito. estimatedCredits então é omitido, e estimatedCreditsUnpriced: { reason: "llm_model_unpriced", modelId, message } diz por quê. A execução dele é recusada. Veja Um modelo ainda sem preço.

Iniciar a execução

curl -s -X POST https://app.nodaro.ai/v1/api/run \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
        "inputs": {
          "text-prompt-1": { "text": "a cat at sunset" }
        }
      }'
{ "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending" }

Consultar periodicamente até a execução terminar

GET /v1/api/status/:execId retorna o status, as contagens de nós e os créditos usados até o momento. Consulte a execução periodicamente, a cada 2 a 5 segundos, até o status ser completed, failed, cancelled, timed_out ou discarded.

Buscar o resultado

GET /v1/api/result/:execId retorna as saídas de uma execução completed ou failed. Para uma execução que terminou como cancelled, timed_out ou discarded, leia o errorMessage da resposta de status: essas execuções não têm payload de resultado, e a rota de resultado continua respondendo 202.

{
  "executionId": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b",
  "status": "completed",
  "outcome": "succeeded",
  "creditsUsed": 50,
  "durationMs": 12450,
  "errorMessage": null,
  "outputs": [
    {
      "nodeId": "generate-image-1",
      "label": "Generate Image",
      "type": "image",
      "url": "https://…/output.png"
    }
  ]
}

O fluxo completo em um único script, e as mesmas chamadas em TypeScript:

BASE="https://app.nodaro.ai"
WORKFLOW_ID="8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f"

EXEC=$(curl -s -X POST "$BASE/v1/api/run" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"workflowId\": \"$WORKFLOW_ID\", \"inputs\": {\"text-prompt-1\": {\"text\": \"a cat at sunset\"}}}" \
  | jq -r .executionId)

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $NODARO_API_KEY" \
    "$BASE/v1/api/status/$EXEC" | jq -r .status)
  echo "Status: $STATUS"
  case "$STATUS" in completed|failed|cancelled|timed_out|discarded) break;; esac
  sleep 5
done

curl -s -H "Authorization: Bearer $NODARO_API_KEY" "$BASE/v1/api/result/$EXEC" | jq .
// The /v1/api/ lane has no dedicated SDK method: call it with client.request.
const schema = await client.request('GET', '/v1/api/schema', {
  query: { workflowId },
})

const { executionId } = await client.request<{ executionId: string }>('POST', '/v1/api/run', {
  body: { workflowId, inputs: { 'text-prompt-1': { text: 'a cat at sunset' } } },
})

const final = ['completed', 'failed', 'cancelled', 'timed_out', 'discarded']
let status = 'pending'
while (!final.includes(status)) {
  await new Promise((r) => setTimeout(r, 3_000))
  ;({ status } = await client.request<{ status: string }>('GET', `/v1/api/status/${executionId}`))
}

const result = await client.request('GET', `/v1/api/result/${executionId}`)

A CLI executa workflows somente com os valores salvos. Para passar valores pelo terminal, publique o workflow como app e execute nodaro apps run <slug> --input prompt="…".

Propriedade

Tipo

Um token com escopo de workflow só pode executar os workflows desse escopo. Qualquer outro workflow responde 403 forbidden. POST /v1/api/run e GET /v1/api/workflows contam para o limite por minuto do token; as leituras de status, de resultado e de schema não contam. Veja Limites de taxa.

Síncrono ou assíncrono

POST /v1/api/run é assíncrono por padrão: ele responde na hora 202 Accepted com { executionId, status: "pending" }, e você consulta a execução periodicamente.

Para um workflow curto, mantenha a conexão aberta até ele terminar:

POST /v1/api/run?wait=true&timeout=120
  • O servidor verifica a execução a cada 5 segundos por até timeout segundos. O padrão é 120, e o máximo é 600.
  • Se a execução terminar a tempo, a resposta é o mesmo payload de GET /v1/api/result/:execId. O status dela é completed, failed, cancelled, timed_out ou discarded.
  • Se não terminar, a resposta é 202 com { executionId, status: "pending" }, e você passa a consultar periodicamente a partir daí.

Use a forma síncrona para execuções que devem terminar em menos de um minuto, como geração de texto e trabalhos leves de imagem. Use a forma assíncrona para workflows que renderizam vídeo ou fazem upscale de vídeo. No SDK, aumente o timeoutMs de createClient para um valor acima do seu timeout, porque o cliente desiste depois de 60 segundos por padrão.

POST /v1/workflows/:id/run e as rotas de geração são sempre assíncronos. Para um único nó, o nodes.runAndWait do SDK consulta a tarefa periodicamente por você: veja Executar um único nó.

Execuções que não encontram nada novo

Uma execução agendada muitas vezes não tem nada a fazer, porque o feed que ela lê não tem posts novos. Uma execução assim termina como completed, não como failed:

  • Um nó que envia texto para um modelo ou uma voz é pulado quando o texto dele está vazio e esse texto veio de um nó que não produziu nada nesta execução. Os nós depois dele também são pulados. Esses nós são Gerar texto, Gerar roteiro, Texto para fala, Gerar música e Texto para áudio.
  • Um nó de saída que envia o que está conectado a ele, como Saída de webhook e os nós de publicação em redes sociais, é pulado quando nenhuma das conexões dele trouxe algo nesta execução.
  • Nada é cobrado por um nó pulado. Um Feed de canal do Telegram que não retorna posts novos não é cobrado.

GET /v1/api/status/:execId, GET /v1/api/result/:execId e a resposta de ?wait=true trazem "outcome": "nothing_new" para uma execução assim. Toda outra execução concluída diz "succeeded". Uma execução que falhou ou foi cancelada não tem outcome, só o status. errorMessage continua null, porque nada deu errado. Em GET /v1/workflow-executions/:id, cada nó pulado mostra { "status": "skipped", "skipReason": "empty_input" }.

Um nó com um prompt digitado continua sendo executado quando a conexão dele está vazia, porque o prompt dele é a requisição. Um nó sem nenhuma conexão continua falhando com o erro de validação de sempre. Só conta uma conexão que não trouxe nada nesta execução.

O que uma execução não pode mudar

Uma requisição de execução não pode redirecionar os nós externos (outbound) de um workflow. Para onde um workflow envia dados e de onde ele os busca é decidido pelo próprio workflow, em todos os endpoints de execução, incluindo POST /v1/workflows/:id/run, POST /v1/api/run e POST /v1/app/:slug/run.

Os nós externos são Saída de webhook e os nós de publicação em redes sociais, como Publicar nas redes. Também são externos os nós de busca, como Extrair da web, Feed de canal do Telegram e URL de vídeo. Nesses nós, uma substituição não pode alterar:

  • campos cujo nome termina em Url ou Urls;
  • target, targets, query, channel, chatId, connectionId, credentialId, platform, webhook, endpoint, host ou privacy;
  • os seletores actor e mode, que escolhem qual campo de destino o nó de busca lê.

A regra vale para valores aninhados em um objeto ou em uma entrada de fieldMappings. Ela vale tanto para um valor vazio quanto para um novo endereço: apagar um destino faria o nó ler, no lugar dele, o texto que vem dos nós anteriores. Uma requisição assim recebe 400 locked_field antes de qualquer coisa ser executada. O erro nomeia até dez dos campos problemáticos e informa quantos são os demais. Uma substituição aninhada a mais de 32 níveis de profundidade em um nó desses é recusada de imediato.

Os campos comuns desses nós, como uma legenda ou um limite, e os campos de mídia url dos nós de entrada, como uploads e áudio de referência, continuam podendo ser substituídos.

Uma execução também não pode mudar o que um nó Sub-workflow executa. Os campos workflowId, selectedRouteId e routeSnapshot dele respondem 400 locked_field, seja definidos diretamente ou por uma entrada de fieldMappings. Qual workflow o nó executa, e qual parte dele, é decidido pelo próprio workflow.

Em um nó de vídeo UGC, uma execução só pode definir source, gender e photoUrl do Criador UGC e targetDurationSec do Roteiro UGC. Qualquer outro campo, como um resultado mantido, um roteiro ou um clipe, responde 400 locked_field. Uma execução de um Criador UGC configurado como Minha foto que não envia uma foto da própria pessoa que executa responde 400 ugc_photo_required antes de qualquer cobrança. Veja Criador UGC e Um vídeo UGC em um app.

Em um app publicado, um modelo ou uma configuração rápida exposta cujas opções são uma lista fixa fica limitada a essa lista: um valor fora dela responde 400 validation_error. O mesmo vale para um número fora do intervalo de uma configuração. Um null em inputOverrides limpa esse campo do nó na execução, e o padrão do próprio nó se aplica. Já uma entrada simples null é descartada, e o valor salvo se aplica. Veja Campos de modelo e de configuração rápida.

Correções de parâmetros

As rotas de geração de imagem e de vídeo aceitam um único vocabulário para aspectRatio, resolution e quality, qualquer que seja o modelo. As rotas de imagem também aceitam background, outputFormat, gifFrames, gifFrameDurationMs e svgLevel nele. Nenhum modelo aceita todos esses valores. Em vez de rejeitar um valor que o modelo escolhido não aceita, o servidor o corrige para um valor que o modelo aceita e informa o que mudou. Uma rejeição no meio de um workflow faria falhar todos os nós ao lado dele que já tivessem gerado resultados e sido cobrados.

As rotas que corrigem valores são POST /v1/generate-image, /v1/image-to-image, /v1/edit-image, /v1/text-to-video e /v1/generate-video:

{
  "jobId": "0f1a9c2e-5b7d-4e8a-9c31-6d2f8b4a7e10",
  "adjustments": [
    {
      "field": "aspectRatio",
      "from": "3:2",
      "to": "auto",
      "reason": "GPT Image 2 does not support aspectRatio \"3:2\" — using \"auto\" instead. Supported: auto, 1:1, 16:9, 9:16, 4:3, 3:4."
    }
  ]
}
  • adjustments não aparece quando nada mudou. A resposta de uma requisição válida é exatamente { "jobId": "…" }.
  • to não aparece quando o modelo não tem essa configuração e o valor foi descartado, por exemplo um aspectRatio enviado a um upscaler.
  • Os créditos seguem o valor corrigido. Uma requisição ao GPT Image 2.5 Flare com 9:8 em 2K é renderizada e cobrada em 1K, porque o GPT Image 2.5 só renderiza 9:8 em 1K.
  • aspectRatio: "auto" mantém o formato da sua foto em /v1/image-to-image e /v1/edit-image. Um modelo com o próprio auto que mantém o formato o recebe como está. Em um modelo sem ele, o servidor lê o tamanho de imageUrl, usa a proporção mais próxima que o modelo aceita e informa a escolha em adjustments. O GPT Image 2.6 (gpt-image-2-6-*) é tratado do mesmo jeito, porque o auto dele renderiza uma foto em retrato como quadrada. Por exemplo, um retrato de 1104x1472 enviado para seedream-5-pro-i2i é renderizado em 3:4, e um de 768x1024 enviado para gpt-image-2-6-flare-i2i também é renderizado em 3:4. Quando o tamanho não pode ser lido, auto volta para a primeira proporção listada do modelo, ou para o próprio auto do modelo no GPT Image 2.6. A proporção nunca muda o preço nesses modelos. auto continua sendo uma opção em todo modelo que o lista: só muda o que é enviado.
  • /v1/generate-image faz o mesmo quando uma foto está conectada. A foto é a primeira imagem que a requisição envia ao modelo: baseImageUrl (inpaint ou refinamento), quando definida. Sem ela, é a primeira imagem de referência (referenceImageUrls, ou a primeira montada a partir de connectedReferences). Sem uma foto, auto em um modelo sem o próprio auto resulta na primeira proporção listada do modelo, e o GPT Image 2.6 recebe o próprio auto.
  • Sem aspectRatio, alguns modelos de edição usam auto. Em /v1/image-to-image, uma requisição a gpt-image-2-6-flare-i2i (o padrão), gpt-image-2-6-sunburst-i2i, gpt-image-2-6-economy-i2i, gpt-image-2-5-flare-i2i, gpt-image-2-5-sunburst-i2i, gpt-image-2-i2i, minimax-h3-image-i2i ou seedream-5-5-i2i que não indica proporção é executada como uma que envia "auto". Ela não usa o padrão 16:9 do modelo. O GPT Image 2 e o 2.5 recebem o próprio auto, que mantém o formato da foto. O MiniMax H3 Image recebe o próprio auto, que segue a primeira imagem, e o Seedream 5.5 recebe o próprio auto. O GPT Image 2.6 recebe a proporção mais próxima da foto, como acima. A tarefa registra a proporção enviada, e o preço é o mesmo, porque esses modelos cobram pela qualidade, pelo tamanho e pelo número de imagens de entrada. Todo outro modelo mantém o próprio padrão quando nenhuma proporção é indicada.
  • outputFormat é corrigido do mesmo jeito, nos modelos que listam outputFormats em GET /v1/models. Os valores são png (o padrão), jpeg, webp, gif e svg. As configurações que dependem do formato o acompanham:
    • GIF: de 2 a 16 quadros quadrados de 512×512. aspectRatio vira 1:1 e resolution é descartado, e cada mudança é informada, exceto uma proporção auto. gifFrames (de 2 a 16, padrão 9) e gifFrameDurationMs (de 20 a 2.000 ms em passos de 10, padrão 200) são movidos para dentro do intervalo e para o passo. Quando você os omite, a tarefa registra os padrões.
    • SVG: svgLevel (standard, o padrão, detailed ou max) é corrigido do mesmo jeito. Um background diferente de auto vira auto, porque um SVG não aceita configuração de fundo.
    • Fundo: um fundo transparent só é mantido com png e webp. Com gif ou jpeg, ele vira auto, isso é informado, e o tamanho não é movido para 1K.
    • Outros formatos: um formato que o modelo não grava passa para o primeiro formato do modelo, e um modelo sem formatos descarta o campo. Configurações de GIF ou SVG enviadas com outro formato são ignoradas sem um ajuste.
    • Máscaras: um maskUrl com gif ou svg é um 400, antes de qualquer reserva.
    • Preço: PNG, JPEG e WebP têm o mesmo preço. Um GIF é cobrado pela qualidade e pela faixa de quadros (2–8, 9–12 ou 13–16), e um SVG como o PNG no tamanho dele mais o nível. Veja os formatos do Gerar imagem.
    • Resultado: o output_data da tarefa indica o tipo do arquivo armazenado em imageMimeType (image/jpeg, image/webp, image/gif ou image/svg+xml), com width e height. Um GIF ou um SVG também ganha uma imagem PNG estática em thumbnailUrl. Um SVG é limpo antes de ser armazenado. Um SVG que não pode ser lido com segurança faz a tarefa falhar, e a tarefa é reembolsada.
  • maskUrl em /v1/image-to-image é a máscara de inpainting do próprio modelo: branco é a área a mudar, e preto é a área a manter. Ela vale no ideogram-edit, no flux-fill, no gpt-image-2-6-flare-i2i e no gpt-image-2-6-sunburst-i2i, os modelos cuja entrada em GET /v1/models lista o recurso mask. Os outros modelos a ignoram.
    • O GPT Image 2.6 mantém o resto da imagem. O modelo redesenha a imagem inteira, então a origem (imageUrl) é colada de volta em tudo fora da máscara, com uma borda suave de alguns pixels dentro da área pintada. Cinza na máscara é uma mudança parcial, então uma borda suave continua suave. O output_data.maskComposited da tarefa é true.
    • O resultado tem o tamanho de imageUrl, no formato que você pediu. Um PNG mantém os pixels da própria origem fora da máscara. Um JPEG ou WebP é codificado mais uma vez.
    • No GPT Image 2.6, o tamanho e o formato seguem a foto. Qualquer aspectRatio vira auto, a proporção aceita mais próxima da foto. resolution vira o tamanho (1K, 2K ou 4K) cujo lado maior é o mais próximo do lado maior da foto. A execução é cobrada nesse tamanho, e as duas mudanças voltam em adjustments. Quando o tamanho da foto não pode ser lido, a resolution que você pediu é mantida.
    • Uma máscara não custa nada a mais. A execução é cobrada como a mesma edição sem máscara nesse tamanho, e a máscara não conta como imagem de entrada.
  • Os workflows salvos também são corrigidos. Um workflow salvo pela API ou pelo MCP recebe as mesmas correções quando é gravado. A exceção é auto em um nó de gerar imagem, de imagem para imagem, de modificar imagem ou de editar imagem: ele é mantido e resolvido com base na foto quando o workflow é executado.
  • Os valores aceitos por cada modelo estão em GET /v1/models. Veja Descobrir modelos.

Correções nas rotas de vídeo

/v1/text-to-video e /v1/generate-video retornam adjustments no mesmo formato. /v1/generate-video também repete o reason de cada correção no array warnings, junto com avisos que não são sobre parâmetros, como voice_unsupported_for_provider. Leia adjustments quando precisar saber qual configuração mudou. Os dois nunca divergem.

  • Um valor não aceito vai para a opção mais próxima, nunca para a mais barata nem para a primeira. Uma requisição 4k em um modelo que vai até 1080p renderiza em 1080p, não em 480p, e um 9:21 vertical vira 9:16, não 16:9.
  • Uma resolution omitida é enviada na faixa em que é cobrada. Quando a plataforma declara a faixa padrão de um modelo, você é cobrado por essa faixa, e é essa faixa que o modelo recebe. O valor aparece no input_data da tarefa, então você sempre pode ver o que foi enviado.
  • A grafia é normalizada antes do cálculo do preço. 4K é lido como 4k, então é cobrado e renderizado na faixa 4K.
  • Alguns modelos renderizam uma faixa fixa para qualquer outro valor. O MiniMax H3 renderiza em 2K tudo o que não for 768P. A família Wan 3.0 e o PixVerse V6 Max renderizam em 720p, e o Grok Imagine 1.5 renderiza em 480p. Nesses casos, a correção aponta para a faixa que o modelo vai produzir, então o preço corresponde à renderização. A entrada do modelo em GET /v1/models declara isso em unlistedResolutionRendersAs.
  • A duração é cobrada pelo tamanho que o modelo renderiza. Uma requisição sem duration renderiza, e é cobrada por, a duração padrão do próprio modelo, defaultDuration em GET /v1/models. Uma duration que o modelo não oferece vai para a duração mais próxima que ele oferece, e um empate vai para a menor. A mudança é informada em adjustments. Por exemplo, uma requisição de 7 segundos no Kling renderiza e cobra 5 segundos, e em um modelo LTX 2.3 renderiza e cobra 6 segundos.
  • duration: -1 significa Automática nos modelos que oferecem essa opção, a família Seedance 2 (autoDuration: true em GET /v1/models). O modelo escolhe a duração do clipe, que é a duração do clipe de origem quando ele edita um vídeo de referência. Uma execução com duração Automática reserva créditos para o clipe mais longo do modelo e reembolsa a diferença até a duração entregue. Com vídeos de referência medidos, ela reserva a duração do vídeo de referência mais longo, arredondada para cima até o segundo inteiro, mais um segundo, nunca acima do clipe mais longo do modelo. Isso porque o modelo pode editar qualquer um deles. Uma solicitação do Seedance 2.5 que declara referenceTaskType: "reference" com duração Automática é reservada na saída mais longa que o modelo consegue fazer, e cobrada pelo que fizer. Veja Tipo de tarefa de referência do Seedance 2.5. Os outros modelos ignoram -1 e renderizam na duração padrão.

As rotas de imagem de personagem e de local (/v1/generate-character, /v1/generate-character-asset, /v1/generate-location e /v1/generate-location-asset) corrigem quality e resolution da mesma forma, mas não retornam adjustments. O valor corrigido só fica visível no input_data da tarefa, em GET /v1/jobs/:id.

Gerenciar workflows

Listar e ler

GET /v1/projects/:projectId/workflows retorna os workflows de um projeto sem nodes, edges e settings. GET /v1/workflows/:id retorna um workflow completo. Em uma organização, a lista segue o espaço de trabalho em que você atua: veja Espaços de trabalho.

curl -s https://app.nodaro.ai/v1/projects/$PROJECT_ID/workflows \
  -H "Authorization: Bearer $NODARO_API_KEY" | jq '.data[] | {id, name}'
const { data: workflows } = await client.workflows.list({ projectId })
const { data: workflow } = await client.workflows.get(workflows[0].id)
console.log(workflow.nodes.length)
nodaro workflows list --project $PROJECT_ID --json
nodaro workflows get 8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f

Criar e atualizar

Crie um workflow em um projeto com POST /v1/projects/:projectId/workflows. Tudo, exceto o projeto, é opcional e usa os padrões do servidor quando omitido:

const { data: wf } = await client.workflows.create({
  projectId,
  name: 'My workflow',
  nodes: [],
  edges: [],
})

PATCH /v1/workflows/:id altera qualquer subconjunto de campos. Para proteger uma atualização contra uma edição simultânea, envie expectedVersion, o inteiro version da sua última leitura. Se o workflow mudou desde então, a atualização é recusada com 409 workflow_conflict, e o erro traz currentVersion, currentUpdatedAt e currentRecord, que é o workflow atual completo. Mescle sua alteração em currentRecord e salve de novo, sem uma leitura extra. expectedUpdatedAt, um timestamp, funciona do mesmo jeito.

import { WorkflowConflictError } from '@nodaro/sdk'

try {
  await client.workflows.update(id, { name: 'Renamed', expectedVersion: 7 })
} catch (err) {
  if (err instanceof WorkflowConflictError && err.currentRecord) {
    await client.workflows.update(id, { name: 'Renamed', expectedVersion: err.currentVersion })
  } else throw err
}
  • Os valores de estado de execução no data de um nó, como o status de execução, a tarefa atual e o progresso, são removidos ao salvar e nunca são armazenados.
  • thumbnailUrl define a imagem de prévia do workflow a partir de uma imagem já hospedada. null remove a imagem.
  • Um salvamento que envia só edges e conecta uma camada de Sobreposição em vídeo reescreve esse nó. Por isso, ele responde 409 workflow_conflict quando o workflow mudou desde a leitura, mesmo sem expectedVersion.
  • visibility é private ou workspace. Só o criador ou um administrador do espaço de trabalho pode alterá-la, e um workflow fora de um espaço de trabalho responde 400 not_workspace_scoped.

Excluir

DELETE /v1/workflows/:id exclui um workflow. O criador e um administrador do espaço de trabalho podem excluí-lo; um colaborador, nunca. Excluir um workflow que não existe, ou que você não pode ver, responde 404, então uma exclusão nunca é um sucesso silencioso. Um colaborador que pode ver o workflow, mas não pode excluí-lo, recebe 403.

Exportar e importar

GET /v1/workflows/:id/export retorna o workflow como um pacote JSON portátil. Com ?assets=true, o pacote também leva os personagens, objetos e locais que o workflow usa, se forem seus. Quando os nós apontam para mídias que outra instalação não consegue buscar, como arquivos em localhost ou em uma rede privada, o pacote as lista em portability.unreachableMedia. Quem tem acesso de visualização recebe o workflow sem os rascunhos do Studio do dono: os espaços de mídia vazios, as marcas de execuções em andamento e os planos de voz das tomadas. O pacote, então, não leva nenhuma entidade que só essas partes usam. GET /v1/workflows/:id deixa de fora as mesmas partes para quem tem acesso de visualização.

POST /v1/workflows/import cria um workflow a partir de um pacote:

POST /v1/workflows/import
{ "projectId": "<project uuid>", "workflow_json": { "version": 1, "name": "…", "nodes": [], "edges": [] } }

A importação recria na sua conta os personagens, objetos, criaturas e locais do pacote e faz os nós apontarem para eles. Ela copia as mídias acessíveis para o armazenamento desta instalação: até 25 arquivos para as mídias do workflow e mais 25 para as entidades do pacote, com imagens de até 20 MB e vídeo ou áudio de até 50 MB. A resposta traz o novo workflow e um importReport:

CampoSignificado
rehostedQuantos arquivos foram copiados para esta instalação.
unreachableMídias em hosts privados, que continuam apontando para onde estavam. Esses nós não são executados até o arquivo ser enviado de novo.
skippedMídias que não puderam ser copiadas, com o motivo, como HTTP 404.
assetIdMapCada id de entidade do pacote, mapeado para o registro criado para ela.
assetsSkippedEntidades que não couberam na sua cota de armazenamento. O workflow é criado mesmo assim.

Pela CLI: nodaro workflows export <id> --with-assets --output bundle.json e depois nodaro workflows import bundle.json --project <projectId>. Leia Importação e exportação para saber o que é transferido.

Conversas MCP

GET /v1/mcp-conversations?month=2026-10&sources=claude,chatgpt

Esta rota lista as suas conversas MCP de um mês, das mais recentes para as mais antigas. Cada conversa é um workflow que um assistente montou a partir das etapas dele. Veja As conversas MCP viram workflows. Um token OAuth precisa de workflows:read.

QuerySignificado
monthYYYY-MM. O padrão é o mês mais recente que tem conversas.
sourcesAs origens a manter, separadas por vírgulas: claude, claude-code, chatgpt ou o nome de outro cliente em minúsculas. O padrão é todas as origens.

A resposta contém:

  • month: o mês listado.
  • months: todos os meses que têm conversas, dos mais recentes para os mais antigos, com a contagem de cada um.
  • sources: as origens do mês listado, com as contagens. Uma origem reúne as conexões de um mesmo produto: “Claude Code (nodaro)” e “Claude Code (staging)” são uma única origem claude-code. connections as lista.
  • data: as conversas. Cada conversa tem:
    • id e projectId. Uma conversa é um workflow, então você a abre, renomeia, exporta, copia ou exclui com as rotas de workflows.
    • name, client, clientLabel e clientName.
    • startedAt, lastActivityAt e live. live é true enquanto a última etapa tem menos de 30 minutos.
    • firstRequest: o seu primeiro pedido, quando o assistente o passou.
    • nodeCount, e counts por tipo: image, video e audio.
    • credits: os créditos cobrados pelas tarefas dela, ou null onde os créditos não são cobrados.
    • cover: { url, kind, setByUser }. É a capa que você definiu, ou então o último resultado.

DELETE /v1/workflows/:id em uma conversa exclui o workflow dela. As tarefas que o assistente fez não ficam arquivadas no workflow, então as imagens e os vídeos delas continuam na sua biblioteca. As execuções iniciadas no editor são excluídas junto, como em qualquer workflow. O workflow central de um mês não pode ser excluído: a rota responde 409 mcp_hub. Uma chave de API pessoal limitada a alguns workflows não pode listar conversas e recebe 403.

Mover para outro projeto

POST /v1/workflows/:id/move
{ "projectId": "…" }

Mover é uma gravação no workflow, então um token OAuth precisa de workflows:write. PATCH /v1/workflows/:id com um projectId faz a mesma coisa e segue as mesmas regras. Você pode mover o trabalho que criou. Dentro de uma organização, um administrador de espaço de trabalho também pode mover trabalho entre dois espaços de trabalho que administra. Um projeto pessoal precisa ser seu nos dois lados.

StatusCódigoSignificado
400validation_errorO workflow já está nesse projeto.
403not_permittedVocê não pode mover esse workflow, ou não pode movê-lo para esse destino.
404not_foundO workflow não existe, ou o projeto não existe para você.
409move_blockedO trabalho foi criado para uma atividade.
409workspace_archivedO espaço de trabalho de destino está arquivado.

Uma movimentação que muda de espaço de trabalho remove as concessões de acesso dos colaboradores do workflow e as informa, para que você possa avisar as pessoas que perderam o acesso:

{
  "data": { "id": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f", "projectId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716" },
  "droppedCollaborators": [{ "userId": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f70812", "name": "Sam" }]
}

A forma com PATCH só inclui droppedCollaborators quando alguma concessão foi removida.

As duas formas retornam o workflow movido em data, como ele ficou. Quando o seu próprio acesso a ele depois da movimentação fica abaixo de edit, você o recebe como um leitor com view o recebe. Isso acontece, por exemplo, quando um administrador de espaço de trabalho move o trabalho de um membro para um espaço de trabalho em que os administradores só podem ver o trabalho. Veja Espaços de trabalho e organizações.

Escopos OAuth para workflows

EscopoRotas
workflows:readGET /v1/projects/:projectId/workflows, GET /v1/workflows, GET /v1/workflows/:id, GET /v1/workflows/:id/export, GET /v1/mcp-conversations
workflows:writeCriar, atualizar, excluir, importar e mover, além de POST /v1/workflows/:parentId/sub-workflows
workflows:executePOST /v1/workflows/:id/run

Tokens de API pessoais não precisam de escopos. Veja Apps OAuth.

Nós de produções do Studio

Alguns nós do canvas pertencem a uma produção do Studio e dependem de quadros vinculados. Eles precisam ser gerados pela API de produções do Studio: executá-los por POST /v1/workflows/:id/run, ou gerar um deles diretamente, responde 400 sequence_execution_required. Veja Produções do Studio.

Perguntas frequentes

Como executo um workflow do Nodaro pela API?

Envie POST /v1/workflows/:id/run. Essa rota executa o workflow salvo e responde 202 com um executionId, que você consulta periodicamente. Para mudar os valores de entrada de uma única execução, adicione um objeto inputOverrides com chaves pelo id do nó, ou use POST /v1/api/run com um objeto inputs.

Como passo valores de entrada para a execução de um workflow?

Envie um objeto inputs para POST /v1/api/run, com chaves pelo id do nó ou por um rótulo único de nó, e o campo do nó dentro de cada chave, por exemplo text. GET /v1/api/schema lista os campos de entrada de um workflow.

Posso aguardar o resultado de um workflow em uma única requisição?

Sim. Adicione ?wait=true&timeout=120 a POST /v1/api/run. O servidor mantém a conexão aberta por até 600 segundos e retorna as saídas. Se a execução ainda estiver em andamento, ele responde 202 com o executionId, e você passa a consultar periodicamente a partir daí.

Por que a API mudou a proporção ou a resolução que eu enviei?

O modelo que você escolheu não aceita esse valor. Em vez de fazer a execução falhar, o Nodaro corrigiu o valor para o mais próximo que o modelo aceita. A resposta lista cada alteração em adjustments, e os créditos são cobrados pelo valor corrigido.

Uma execução pela API pode mudar para onde um workflow envia os resultados?

Não. Os campos de destino dos nós externos, como a URL de um nó Saída de webhook ou a conta de um nó de publicação em redes sociais, não podem ser substituídos por uma execução. Uma requisição que tenta fazer isso recebe 400 locked_field.

Última atualização

Nesta página