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étodo | Caminho | O que faz |
|---|---|---|
POST | /v1/workflows/:id/run | Executa o workflow salvo, ou alguns dos nós dele. Responde 202 com um executionId. |
POST | /v1/workflows/:id/render-final/estimate | Cota uma Renderização final: os nós que ela executa e os créditos dela. Não cria nem cobra nada. |
GET | /v1/api/workflows | Lista 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/run | Executa um workflow com novos valores de entrada. Adicione ?wait=true&timeout=… para aguardar o resultado. |
GET | /v1/api/status/:execId | O 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/:execId | As saídas da execução, quando o status dela for completed ou failed. |
POST | /v1/app/:slug/run | Executa um app publicado com os campos do formulário dele. Veja Miniapps. |
Gerenciar workflows
| Método | Caminho | O que faz |
|---|---|---|
GET | /v1/projects/:projectId/workflows | Os workflows de um projeto, sem os nós e as conexões. |
GET | /v1/workflows | Os seus workflows de todos os projetos. |
GET | /v1/workflows/:id | Um workflow com os nós, as conexões e as configurações dele. |
POST | /v1/projects/:projectId/workflows | Cria um workflow em um projeto. |
PATCH | /v1/workflows/:id | Altera qualquer subconjunto dos campos de um workflow. |
DELETE | /v1/workflows/:id | Exclui um workflow. |
GET | /v1/workflows/:id/export | Exporta o workflow como um pacote JSON. Adicione ?assets=true para incluir os personagens, objetos e locais dele. |
POST | /v1/workflows/import | Cria um workflow a partir de um pacote. |
POST | /v1/workflows/:id/move | Move um workflow para outro projeto. |
GET | /v1/workflows/shared-with-me | Os workflows que outras pessoas compartilharam com você. |
GET | /v1/mcp-conversations | As 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
| Endpoint | Credencial | Valores de entrada | Use quando |
|---|---|---|---|
POST /v1/workflows/:id/run | Qualquer 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/run | Um token de API pessoal | inputs 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/run | Qualquer token | Os campos do formulário do app, mais substituições diretas de campos de nós | O 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-1Propriedade
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.
| Status | Código | Significado |
|---|---|---|
| 402 | insufficient_credits | Uma continuação ou uma Renderização final que seus créditos não cobrem. Nada foi criado. |
| 403 | forbidden | Você 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. |
| 404 | not_found | O workflow não existe, ou você não pode vê-lo. |
| 409 | already_running | O 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
inputOverridesda execução anterior são aplicados de novo. OsinputOverridesque 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:
| Status | Código | Significado |
|---|---|---|
| 400 | continuation_subset_required | nodeIds está ausente ou vazio, sem continueMode. |
| 400 | continuation_workflow_mismatch | A execução anterior executou outro workflow. |
| 400 | continuation_version_mismatch | A 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. |
| 400 | validation_error | continueFromExecutionId não é um id de execução. |
| 404 | continuation_not_found | A execução não existe, ou não é sua. |
| 409 | continuation_not_completed | A 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
inputOverridesda 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, semcontinueMode. 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 resposta202indica emcontinuedFroma 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 emexecutionId, as renderizações dela emrenderNodeIdse os nós Enxugar episódio dela emreviewNodeIds. O camponextdela é a execução que os conclui: envienextcomo corpo dePOST /v1/workflows/:id/run. - O saldo é conferido antes. Uma continuação que seus créditos não cobrem é recusada com
402 insufficient_creditsantes 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:
| Status | Código | Significado |
|---|---|---|
| 409 | continuation_not_failed | A execução não falhou. |
| 409 | continuation_superseded | Uma 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 }. |
| 409 | continuation_preview_pending | A continuação mais recente parou em uma prévia. Envie o next dela antes. |
| 409 | continuation_subset_required | Nã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. |
| 409 | already_running | Uma 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 } }:
nodeIdseinputOverridessã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 acrescentaestimatedCreditsIsEstimate: 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.holdCreditsnunca é menor queestimatedCredits.sufficientdiz se os seus créditos cobrem essa reserva, eavailableé o seu saldo de créditos disponível.availableénullquando 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
nullem 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:
| Status | Código | Significado |
|---|---|---|
| 400 | render_final_node_not_found | O workflow não tem nenhum nó com esse id. |
| 400 | render_final_not_a_render | O nó não é uma renderização do Aplicar EDL. |
| 400 | validation_error | renderFinal 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.
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é
timeoutsegundos. 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. Ostatusdela écompleted,failed,cancelled,timed_outoudiscarded. - Se não terminar, a resposta é
202com{ 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
UrlouUrls; target,targets,query,channel,chatId,connectionId,credentialId,platform,webhook,endpoint,hostouprivacy;- os seletores
actoremode, 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."
}
]
}adjustmentsnão aparece quando nada mudou. A resposta de uma requisição válida é exatamente{ "jobId": "…" }.tonão aparece quando o modelo não tem essa configuração e o valor foi descartado, por exemplo umaspectRatioenviado a um upscaler.- Os créditos seguem o valor corrigido. Uma requisição ao GPT Image 2.5 Flare com
9:8em2Ké renderizada e cobrada em 1K, porque o GPT Image 2.5 só renderiza9:8em 1K. aspectRatio: "auto"mantém o formato da sua foto em/v1/image-to-imagee/v1/edit-image. Um modelo com o próprioautoque mantém o formato o recebe como está. Em um modelo sem ele, o servidor lê o tamanho deimageUrl, usa a proporção mais próxima que o modelo aceita e informa a escolha emadjustments. O GPT Image 2.6 (gpt-image-2-6-*) é tratado do mesmo jeito, porque oautodele renderiza uma foto em retrato como quadrada. Por exemplo, um retrato de 1104x1472 enviado paraseedream-5-pro-i2ié renderizado em3:4, e um de 768x1024 enviado paragpt-image-2-6-flare-i2itambém é renderizado em3:4. Quando o tamanho não pode ser lido,autovolta para a primeira proporção listada do modelo, ou para o próprioautodo modelo no GPT Image 2.6. A proporção nunca muda o preço nesses modelos.autocontinua sendo uma opção em todo modelo que o lista: só muda o que é enviado./v1/generate-imagefaz 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 deconnectedReferences). Sem uma foto,autoem um modelo sem o próprioautoresulta na primeira proporção listada do modelo, e o GPT Image 2.6 recebe o próprioauto.- Sem
aspectRatio, alguns modelos de edição usamauto. Em/v1/image-to-image, uma requisição agpt-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-i2iouseedream-5-5-i2ique 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óprioauto, que mantém o formato da foto. O MiniMax H3 Image recebe o próprioauto, que segue a primeira imagem, e o Seedream 5.5 recebe o próprioauto. 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 listamoutputFormatsemGET /v1/models. Os valores sãopng(o padrão),jpeg,webp,gifesvg. As configurações que dependem do formato o acompanham:- GIF: de 2 a 16 quadros quadrados de 512×512.
aspectRatiovira1:1eresolutioné descartado, e cada mudança é informada, exceto uma proporçãoauto.gifFrames(de 2 a 16, padrão 9) egifFrameDurationMs(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,detailedoumax) é corrigido do mesmo jeito. Umbackgrounddiferente deautoviraauto, porque um SVG não aceita configuração de fundo. - Fundo: um fundo
transparentsó é mantido compngewebp. Comgifoujpeg, ele viraauto, 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
maskUrlcomgifousvgé um400, 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_datada tarefa indica o tipo do arquivo armazenado emimageMimeType(image/jpeg,image/webp,image/gifouimage/svg+xml), comwidtheheight. Um GIF ou um SVG também ganha uma imagem PNG estática emthumbnailUrl. 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.
- GIF: de 2 a 16 quadros quadrados de 512×512.
maskUrlem/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 noideogram-edit, noflux-fill, nogpt-image-2-6-flare-i2ie nogpt-image-2-6-sunburst-i2i, os modelos cuja entrada emGET /v1/modelslista o recursomask. 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. Ooutput_data.maskCompositedda 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
aspectRatioviraauto, a proporção aceita mais próxima da foto.resolutionvira o tamanho (1K,2Kou4K) cujo lado maior é o mais próximo do lado maior da foto. A execução é cobrada nesse tamanho, e as duas mudanças voltam emadjustments. Quando o tamanho da foto não pode ser lido, aresolutionque 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.
- O GPT Image 2.6 mantém o resto da imagem. O modelo redesenha a imagem inteira, então a origem (
- 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 é
autoem 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
4kem um modelo que vai até 1080p renderiza em 1080p, não em 480p, e um9:21vertical vira9:16, não16:9. - Uma
resolutionomitida é 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 noinput_datada tarefa, então você sempre pode ver o que foi enviado. - A grafia é normalizada antes do cálculo do preço.
4Ké lido como4k, 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 emGET /v1/modelsdeclara isso emunlistedResolutionRendersAs. - A duração é cobrada pelo tamanho que o modelo renderiza. Uma requisição sem
durationrenderiza, e é cobrada por, a duração padrão do próprio modelo,defaultDurationemGET /v1/models. Umadurationque 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 emadjustments. 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: -1significa Automática nos modelos que oferecem essa opção, a família Seedance 2 (autoDuration: trueemGET /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 declarareferenceTaskType: "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-1e 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-7a8b9c0d1e2fCriar 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
datade um nó, como o status de execução, a tarefa atual e o progresso, são removidos ao salvar e nunca são armazenados. thumbnailUrldefine a imagem de prévia do workflow a partir de uma imagem já hospedada.nullremove a imagem.- Um salvamento que envia só
edgese conecta uma camada de Sobreposição em vídeo reescreve esse nó. Por isso, ele responde409 workflow_conflictquando o workflow mudou desde a leitura, mesmo semexpectedVersion. visibilityéprivateouworkspace. Só o criador ou um administrador do espaço de trabalho pode alterá-la, e um workflow fora de um espaço de trabalho responde400 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:
| Campo | Significado |
|---|---|
rehosted | Quantos arquivos foram copiados para esta instalação. |
unreachable | Mí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. |
skipped | Mídias que não puderam ser copiadas, com o motivo, como HTTP 404. |
assetIdMap | Cada id de entidade do pacote, mapeado para o registro criado para ela. |
assetsSkipped | Entidades 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,chatgptEsta 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.
| Query | Significado |
|---|---|
month | YYYY-MM. O padrão é o mês mais recente que tem conversas. |
sources | As 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 origemclaude-code.connectionsas lista.data: as conversas. Cada conversa tem:ideprojectId. Uma conversa é um workflow, então você a abre, renomeia, exporta, copia ou exclui com as rotas de workflows.name,client,clientLabeleclientName.startedAt,lastActivityAtelive.liveétrueenquanto a última etapa tem menos de 30 minutos.firstRequest: o seu primeiro pedido, quando o assistente o passou.nodeCount, ecountspor tipo:image,videoeaudio.credits: os créditos cobrados pelas tarefas dela, ounullonde 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.
| Status | Código | Significado |
|---|---|---|
| 400 | validation_error | O workflow já está nesse projeto. |
| 403 | not_permitted | Você não pode mover esse workflow, ou não pode movê-lo para esse destino. |
| 404 | not_found | O workflow não existe, ou o projeto não existe para você. |
| 409 | move_blocked | O trabalho foi criado para uma atividade. |
| 409 | workspace_archived | O 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
| Escopo | Rotas |
|---|---|
workflows:read | GET /v1/projects/:projectId/workflows, GET /v1/workflows, GET /v1/workflows/:id, GET /v1/workflows/:id/export, GET /v1/mcp-conversations |
workflows:write | Criar, atualizar, excluir, importar e mover, além de POST /v1/workflows/:parentId/sub-workflows |
workflows:execute | POST /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.
Páginas relacionadas
Execuções
Nós
Incorporar um miniapp
Execução de workflows
Webhooks
Última atualização
Autenticação
Autentique chamadas à API do Nodaro com token de API pessoal, token de app OAuth ou JWT de sessão, e crie, limite, vincule e revogue os seus tokens de API.
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.