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

Incorporar um miniapp

Execute um miniapp do Nodaro no seu produto com o código de incorporação ou um formulário próprio na API REST: entradas, execuções, resultados e erros.

Incorporar um miniapp é executar um app do Nodaro já publicado a partir do seu próprio produto. Você pode colar o código de incorporação do app em uma página, ou criar seu próprio formulário sobre a API REST: ler as entradas do app, iniciar uma execução, consultá-la periodicamente e mostrar o resultado. O app em si fica no Nodaro; o seu produto coleta as entradas e exibe as saídas.

Duas formas de incorporar

Código de incorporaçãoSua própria interface
EsforçoColar uma tag iframe.Criar um formulário e uma pequena rota de servidor.
VisualA visualização de app do Nodaro.O seu próprio design.
Em nome de quem a execução é feitaDe quem está vendo a página, com a própria sessão do Nodaro.Da conta por trás do seu token.

Colar o código de incorporação

Abrir as configurações de incorporação do app

No Nodaro, abra Miniapps, escolha Meus miniapps e clique em Incorporar no card do app.

Permitir o seu domínio

Em Domínios permitidos para incorporação, digite a origem do seu site, como https://example.com, e clique em Adicionar. A incorporação fica bloqueada até que pelo menos um domínio seja adicionado.

Copiar o código para a sua página

Clique em Copiar código de incorporação e cole a tag na sua página:

<iframe src="https://app.nodaro.ai/embed/your-app-slug" width="100%" height="600" frameborder="0" allow="clipboard-write"></iframe>

Criar sua própria interface

O restante desta página cria uma interface web ou mobile personalizada para um app publicado, sobre a API REST. O conteúdo é autossuficiente, então você também pode entregá-lo a um gerador de código com IA: adicione .md à URL desta página para obter uma cópia em Markdown.

Três coisas para saber antes

URL basehttps://app.nodaro.ai no Nodaro Cloud, ou o endereço da sua própria instalação.
Identificador do appO slug: a última parte da URL do app publicado. Para https://app.nodaro.ai/app/my-cool-app, o slug é my-cool-app.
Formato da execuçãoAssíncrono. POST /v1/app/{slug}/run responde na hora com um runId, e você consulta GET /v1/app/{slug}/runs/{runId} periodicamente para obter o resultado. A execução não faz callback.

Dois endpoints públicos, que não precisam de token, informam tudo de que você precisa para o formulário:

  • GET /v1/app/{slug} retorna as entradas e os metadados do app.
  • GET /v1/nodes/{type} retorna os campos de um tipo de nó.

Etapa 1: ler as entradas do app

curl https://app.nodaro.ai/v1/app/<slug>

Os campos que importam para a sua interface:

{
  "id": "uuid",
  "name": "Headline Generator",
  "description": "...",
  "iconUrl": "https://...",
  "version": 3,                        // the latest version
  "estimatedCredits": 5,               // the listed price: a run, with any Render final after it
  "perMinuteCredits": 0,               // per minute of the recording the app is given; 0 when the price does not depend on it
  "perItemCredits": 0,                 // per item beyond the saved items of a list the user fills; 0 when none
  "maxEstimatedCredits": 9,            // "up to": the most a run can cost over the user's choices (with
  "maxPerMinuteCredits": 0,            // maxPerMinuteCredits and maxPerItemCredits); present only when it
  "maxPerItemCredits": 0,              // differs from the "from" figures above
  "estimatedCreditsIsEstimate": true,  // present when the price holds a metered LLM call's estimate: show "~5"
  "runEstimatedCredits": 5,            // the run alone: the listed price without its Render final part
  "runPerMinuteCredits": 0,            // ...and its per-minute and per-item parts
  "runPerItemCredits": 0,
  "editPlanPerMinute": false,          // true when an Edit Plan node is charged per started minute of the recording
  "maxRunsPerUserPerDay": null,        // or a number
  "thumbnailNodeId": "node-abc",       // the node whose output is the main result
  "snapshotNodes": [                   // the workflow's nodes
    {
      "id": "node-abc",
      "type": "generate-image",        // use it in step 2
      "data": {
        "prompt": "default prompt",    // the current value of each field
        "aspectRatio": "1:1"
      }
    }
  ],
  "snapshotEdges": [ /* the connections, rarely needed by your interface */ ],
  "snapshotSettings": {
    "presentationSettings": {
      "inputItems": [                  // the form schema
        { "type": "field", "id": "item-1", "nodeId": "node-abc", "field": "prompt", "allowedValues": null, "maxLength": 1200 },
        { "type": "field", "id": "item-2", "nodeId": "node-abc", "field": "aspectRatio", "allowedValues": ["1:1", "16:9", "9:16"] }
      ]
    }
  },
  "versions": [{ "version": 3, "id": "...", "createdAt": "..." }]
}

inputItems é o formulário que o publicador montou. Percorra a lista, entre em cada group e colete todos os itens field: esse é o seu formulário.

typeRenderize como
fieldUm campo de formulário. Leia nodeId, field, o allowedValues opcional e o maxLength opcional, o limite de caracteres de uma entrada de texto.
nodeO bloco padrão do nó inteiro. Ignore-o em um formulário personalizado, ou renderize todos os campos do nó. Um nó Texto exposto inteiro também pode trazer maxLength.
outputUma prévia ao vivo de um resultado. Ignore-a enquanto monta o formulário e mostre-a depois da execução.
richtextMarkdown estático que o publicador escreveu. Renderize-o como está.
groupUm contêiner com os próprios items. Entre nele; os grupos não se aninham.

Etapa 2: descobrir o tipo de cada campo

inputItems fornece pares de nodeId e field, mas não o tipo do campo: texto, número, escolha. Busque o tipo de nó para saber mais:

curl https://app.nodaro.ai/v1/nodes/generate-image
{
  "data": {
    "type": "generate-image",
    "label": "Generate Image",
    "category": "ai-image",
    "description": "...",
    "outputType": "image",
    "providers": ["nano-banana-pro", "gpt-image-2", "flux"],   // shortened
    "capabilities": ["supports-reference-image", "supports-negative-prompt"]
  }
}

Nem todo descritor de nó tem um inputSchema completo. Quando ele estiver ausente, deduza o controle com estas regras, nesta ordem:

  1. O item de entrada tem allowedValues: um select com essas opções.
  2. O valor atual em snapshotNodes[i].data[field] é um booleano: uma chave liga/desliga.
  3. O valor atual é um número: um campo numérico, ou um controle deslizante quando o nome do campo termina em duration, intensity, strength, scale ou temperature.
  4. O valor atual é uma string, e o nome do campo é prompt, description, text, content, caption ou message: uma área de texto com várias linhas.
  5. O valor atual é uma URL, e o tipo de nó começa com upload-: um upload de arquivo que envia a URL pública do arquivo.
  6. Qualquer outra coisa: um campo de texto de uma linha.

Estes nomes de campo cobrem a maioria dos campos expostos:

Nome do campoControleObservações
prompt, negativePrompt, text, descriptionÁrea de texto
model, provider, voice, style, toneLista suspensaAs opções vêm de allowedValues ou de providers.
aspectRatioLista suspensaNormalmente 1:1, 16:9, 9:16, 4:3 e 3:4.
resolutionLista suspensaNormalmente 1K, 2K e 4K, ou 720p, 1080p e 4k.
qualityLista suspensaNormalmente medium e high.
duration, nFrames, seed, temperatureNúmero
enableTranslation, addAudio, headless, loopChave liga/desliga
imageUrl, videoUrl, audioUrl, referenceImageURLFaça o upload do arquivo primeiro e depois envie a URL dele.

Pelo MCP, get_app_inputs informa o tipo de parte desses campos. Um controle deslizante exposto volta como type: "number", com os próprios min, max e step. Um campo que quem publicou limitou a uma lista de valores volta como type: "select", com essas options. Um campo das configurações rápidas do nó volta como select, number ou boolean; veja Campos de modelo e de configuração rápida. Todos os outros campos voltam como type: "text", então consulte o nó para eles. Uma entrada plana de um controle deslizante aceita um número ou um texto numérico.

Controles deslizantes e chaves. Um controle deslizante ou uma chave começa no valor salvo do nó, em snapshotNodes[i].data[field]. Quando o nó não tem valor salvo, o app mostra o padrão do campo: o valor que um nó novo recebe. Uma execução envia um campo só depois que o usuário o altera. Até lá, vale o valor do próprio nó. Faça o mesmo na sua interface: preencha o controle e envie o campo só quando o seu usuário o alterar. As configurações de voz do Texto para fala aceitam um número ou um texto numérico, e um valor fora da faixa da configuração é ajustado para dentro dela.

Campos de modelo e de configuração rápida

Toda configuração da barra inferior de um nó no editor pode ser exposta em um app: o modelo e, na maioria dos nós de geração, a resolução, a duração, a proporção, o Rascunho e configurações parecidas. Por exemplo, o Vídeo para vídeo pode expor o Modelo, a Resolução e o Rascunho, e o Gerar vídeo, a Duração, a Resolução, a Proporção e o Rascunho ao lado do Modelo. A configuração do número de execuções, Execuções, nunca é oferecida.

  • A chave é o próprio campo de dados do nó, como provider, v2vResolution, duration ou draft. Envie o valor em inputOverrides[nodeId][field], no tipo que o nó guarda: 8 para uma duração, não "8", e true para o Rascunho.
  • Uma lista fixa é aplicada. Algumas configurações oferecem os mesmos valores seja qual for o restante da configuração do nó, como os modelos que um nó oferece, um modelo do Suno ou a proporção de uma cena 3D. Um valor fora da lista é recusado com 400 validation_error (Invalid value for provider: …. Allowed: …). Quem publica pode restringir ainda mais essas listas com allowedValues.
  • Um intervalo é aplicado. Uma configuração que aceita qualquer número dentro de um intervalo, como a Duração de uma cena 3D ou o Limite de uma Máscara de vídeo, recusa um número fora dele com 400 validation_error.
  • Algumas opções dependem do modelo. As resoluções, proporções e durações que uma configuração oferece dependem do modelo do nó. O cartão do app oferece as opções do modelo que a execução vai usar e troca uma opção que o novo modelo não aceita quando o modelo muda. Faça o mesmo no seu formulário: o get_app_inputs do MCP lista os valores de cada modelo para um campo assim, e snapshotNodes[i].data.provider, ou o valor que o seu formulário envia, diz qual modelo é executado.
  • O Rascunho renderiza em 480p. Nos modelos Seedance, o cartão do app também define a resolução como 480p quando o Rascunho é ativado, e o servidor renderiza um rascunho em 480p seja qual for a resolução enviada.

Limpar um campo

Um campo definido como null em inputOverrides é limpo nessa execução: o nó é executado como se não tivesse valor ali, nem null nem o valor salvo pelo criador, então o padrão do próprio nó se aplica. O cartão do app faz isso com uma configuração que o modelo escolhido não tem. Por exemplo, trocar o Vídeo para vídeo para o Runway Aleph, que não tem configuração de resolução, limpa a resolução. O cartão também desativa o Rascunho dessa forma. Um campo limpo nunca é recusado pelo allowedValues nem por uma lista fixa.

Como entrada plana do MCP ou do SDK, null é descartado antes de chegar ao nó, então o valor salvo do nó se aplica. Use inputOverrides para limpar um campo.

Campos de slot do Lottie

Um nó Gráficos animados com o mecanismo Lottie pode expor os slots nomeados dele, como cores, textos e números, como entradas do app. Eles aparecem como itens de campo cujo field começa com slot:, como slot:primaryColor. Os usuários os alteram a cada execução por 0 créditos: quando um app expõe campos de slot, cada execução reaproveita a animação publicada e só troca os valores dos slots.

Valor do slotControleValor a enviar
Uma cor, como um array RGBA de números de 0 a 1Seletor de corUma string hexadecimal, como "#00ff00"
Uma stringCampo de textoA string
Um númeroSliderO número

Um valor de slot não é um campo comum do nó: ele fica em motionPlan.slotValues do nó. Para definir slots por inputOverrides diretos, substitua o motionPlan inteiro do nó por uma cópia do plano publicado cujo slotValues traga as suas alterações, com as cores como arrays RGBA. Um patch parcial de slotValues descartaria o restante do plano. O app do Nodaro e o SDK montam isso para você.

{
  "inputOverrides": {
    "node-mg1": {
      "motionPlan": {
        // ...the published node's motionPlan, unchanged...
        "slotValues": { "primaryColor": [0, 1, 0, 1], "nameText": "Acme Inc." }
      }
    }
  }
}

Entradas de URL de vídeo

Um nó URL de vídeo pode ser uma entrada do app, para que o app receba um episódio como link em vez de um upload. get_app_inputs lista o campo como type: "video", e uma entrada plana é o próprio link:

{ "inputs": { "episode": "https://www.youtube.com/watch?v=VIDEO_ID" } }
  • O que o campo aceita. Um link para a página onde está um vídeo, ou qualquer outro link público http ou https para um vídeo. O link para a página de um vídeo é baixado, e qualquer outro link é usado como está. Um valor que não é um link da web, ou que aponta para um endereço privado, é recusado com 400 locked_field antes que algo seja executado ou cobrado. Um link para um nó URL de vídeo que o app não expõe é recusado da mesma forma.
  • Na página do app. Um link para a página de um vídeo mostra a caixa de direitos de conteúdo abaixo do campo. O usuário do app marca a caixa para confirmar a declaração para o seu link, e nada é buscado antes disso. Um link alterado desmarca a caixa. Quando só Receita de conteúdo lê o link, nada é importado e nenhuma caixa aparece. Dublagem dubla o arquivo, então um link que Dublagem lê é baixado como um link que um nó assiste.
  • O servidor baixa o vídeo. Antes do primeiro nó ser executado, o servidor busca o que os nós depois do link leem. Um nó que assiste ao vídeo recebe o vídeo. Transcrever e Cover com Suno recebem só o som. Dublagem recebe o vídeo, a menos que duble o seu próprio Link de origem. Receita de conteúdo usa o endereço da página, então nada é buscado para ela.
  • Um vídeo longo precisa de um trecho. De um site cuja duração de vídeo o Nodaro lê primeiro, um vídeo de 4 minutos ou mais, ou cuja duração não pode ser lida, é baixado só em parte. Indique o trecho no nó, em inputOverrides, em segundos: { "<nodeId>": { "sectionStartSec": 600, "sectionEndSec": 1200 } }. Sem um trecho, a execução é recusada antes de qualquer cobrança. Uma transmissão ao vivo também é recusada, e um download que falha recusa a execução com o motivo.
  • Substituições diretas. Em inputOverrides, o link vai no campo youtubeUrl do nó.
  • Direitos de conteúdo. A busca do servidor é uma importação do link. Envie a confirmação para esse link e essa execução como o rightsConfirmationId do nó em inputOverrides, de POST /v1/content-rights/confirm. Uma confirmação libera um download dentro de uma hora, por isso nunca é guardada com as entradas salvas. Uma execução sem confirmação só é recusada quando a implantação exige uma confirmação. Veja Direitos de conteúdo.
  • Preço. As etapas depois do link que são cobradas pela duração do vídeo têm preço por minuto dessa gravação, em perMinuteCredits.

Entradas de vídeo UGC

Um app montado com os nós de vídeo UGC, no Nodaro Cloud, tem duas entradas próprias: o cartão do criador e a duração do vídeo.

O cartão do criador. Um item node de um Criador UGC é o cartão do criador: Criador de IA ou Minha foto, Mulher ou Homem e, para Minha foto, o envio da foto de quem executa. O cartão grava três campos do nó, então uma execução os envia no id do nó do criador:

{
  "inputOverrides": {
    "<creator node id>": {
      "source": "photo",
      "gender": "woman",
      "photoUrl": "https://example.com/runner.jpg"
    }
  }
}
  • source é sampled, para um criador de IA, ou photo.
  • gender é woman ou man.
  • photoUrl é a URL pública de uma imagem, só para Minha foto.

O get_app_inputs do MCP lista o cartão como três chaves: a própria chave do criador para source, e a mesma chave com _gender e _photo_url, ambas opcionais. Uma execução de app nunca espera a escolha de um criador: ela sorteia um. Uma execução com Minha foto que não envia uma foto da própria pessoa que executa é recusada com 400 ugc_photo_required antes que algo seja executado ou cobrado.

A duração do vídeo. A Duração do vídeo (segundos) do Roteiro UGC, targetDurationSec, pode ser um item field. Ela é um controle deslizante de 4 a 300 segundos, ou as durações que o app permite em allowedValues, como [15, 20, 25]. Em inputOverrides, envie-a como número: 20, não "20". Uma entrada simples aceita os dois.

Nada mais em um nó UGC pode ser definido por uma execução. Qualquer outro campo de um nó UGC, como um resultado mantido, um roteiro ou um clipe, é recusado com 400 locked_field. Veja Um vídeo UGC em um app.

Etapa 3: montar o formulário

// Adapt to your framework.
type FormField = {
  nodeId: string
  field: string
  label: string                     // "aspectRatio" becomes "Aspect ratio"
  control: "text" | "textarea" | "number" | "toggle" | "select" | "upload"
  options?: Array<string | number | boolean>
  defaultValue: unknown
}

async function buildForm(slug: string, baseUrl: string): Promise<FormField[]> {
  const app = await fetch(`${baseUrl}/v1/app/${slug}`).then((r) => r.json())
  const nodesById = new Map(app.snapshotNodes.map((n) => [n.id, n]))

  const fields: FormField[] = []
  const walk = (items) => {
    for (const it of items ?? []) {
      if (it.type === "group") walk(it.items)
      if (it.type !== "field") continue
      const node = nodesById.get(it.nodeId)
      const current = node?.data?.[it.field]
      fields.push(toFormField(it, node, current))
    }
  }
  walk(app.snapshotSettings?.presentationSettings?.inputItems ?? [])
  return fields
}
  • Use o id do nó como chave dos valores, não o rótulo. O corpo da execução é { "inputOverrides": { "<nodeId>": { "<field>": value } } }.
  • O Nodaro aplica o allowedValues. Um valor fora da lista é recusado com 400 validation_error. O mesmo vale para um valor fora da lista fixa de um campo de configuração rápida.
  • O Nodaro aplica o maxLength. Um texto maior que o limite é recusado com 400 input_too_long. Coloque maxlength na área de texto e mostre um contador. O preço do app considera esse limite para uma entrada de fala.
  • O Nodaro aplica os limites dos seletores. Quem publica pode limitar um seletor, como Cenário, Clima ou Pessoa, a uma parte do catálogo, em snapshotSettings.presentationSettings.cardMeta[nodeId]. Um seletor de uma dimensão usa pickerAllowedValues, e um seletor de várias dimensões usa pickerAllowedValuesByField ({ field: [ids] }). Um valor fora da lista é recusado com 400 validation_error em todas as execuções do app, inclusive as execuções pela API. Para retirar uma escolha, omita o campo ou envie um valor vazio. Não envie o padrão do catálogo.
  • Preencha os valores padrão a partir de snapshotNodes[i].data, para que um usuário que não altere nada ainda tenha uma execução útil.
  • Mostre estimatedCredits, para que os usuários saibam o custo antes de executar. Quando perMinuteCredits ou perItemCredits não é 0, o preço cresce com a duração da gravação ou com o número de itens da lista: mostre uma parte fixa mais essas partes. estimatedCredits inclui qualquer renderização final, e runEstimatedCredits, com as partes por minuto e por item, é só a execução. Quando maxEstimatedCredits está presente, o preço depende do que o usuário escolhe: mostre-o como uma faixa, como “a partir de 5 – até 9”. “Até” é o máximo que uma execução pode custar considerando todos os campos expostos, nos valores permitidos por quem publicou quando definidos, nas opções de cada modelo e com um clipe de referência enviado pelo usuário na duração máxima. Uma versão publicada antes de essa faixa existir não traz campos max* até ser publicada de novo. Quando estimatedCreditsIsEstimate é true, o preço inclui a estimativa de uma chamada de LLM. Essa chamada é cobrada pelos tokens que realmente usa, então mostre o preço como ~5, e não 5.
  • Mostre o limite diário quando maxRunsPerUserPerDay estiver definido, como “2 de 5 execuções usadas hoje”, para evitar um 429 inesperado.

Etapa 4: iniciar uma execução e consultá-la periodicamente

Inicie a execução com um token:

curl -X POST https://app.nodaro.ai/v1/app/<slug>/run \
  -H "Authorization: Bearer $NODARO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputOverrides": {
      "node-abc": { "prompt": "a cat astronaut", "aspectRatio": "16:9" }
    }
  }'

A resposta é 202 Accepted:

{ "executionId": "exec-uuid", "runId": "run-uuid", "status": "pending" }
Campo opcional do corpoO que faz
versionExecuta uma versão específica do app. O padrão é a mais recente.
inputsAs entradas do app como um mapa plano de nomes de entrada para valores, do jeito que o SDK e a CLI as enviam. inputOverrides é aplicado sobre inputs, campo por campo, e prevalece onde os dois definem o mesmo campo. Um campo que é um número, como um controle deslizante exposto, aceita um número ou um texto numérico: "0.4" chega como 0.4.
runIdVincula a execução a um rascunho de execução que você criou antes. Você pode ignorar este campo em uma primeira versão.

inputOverrides também pode definir campos de nós que o app não expõe, como promptPrefix; veja Texto antes e depois do prompt. Ele nunca pode mudar para onde um nó externo envia dados ou de onde ele os busca, como o endereço de um nó Saída de webhook, nem qual workflow um nó Sub-workflow executa: essa execução é recusada com 400 locked_field.

Um app com taxa do criador. No Nodaro Cloud, uma execução de um app com taxa do criador é conferida com o saldo de quem executa antes de qualquer coisa ser gravada ou executada. O saldo precisa cobrir o preço de execução anunciado do app com a taxa:

  • A taxa é o preço anunciado sobre o qual ela se aplica, mais a taxa fixa, mais a porcentagem desse preço, arredondada para cima até um crédito inteiro.
  • A taxa fixa conta inteira, mesmo quando o preço anunciado é 0.
  • Uma execução que o saldo não cobre é recusada com 402 insufficient_credits. A mensagem informa o preço da execução com a taxa, a taxa e o saldo.
  • O criador que executa o próprio app não paga taxa e não é conferido.

Em uma execução paga por um espaço de trabalho de uma organização, o espaço de trabalho paga a taxa quando a organização dele aprovou o app. Caso contrário, quem executa paga a taxa:

  • A execução de um app aprovado é recusada com o próprio 402 budget_exceeded do espaço de trabalho quando a margem disponível do orçamento não cobre o preço anunciado com a taxa.
  • Um app que a organização não aprovou é recusado com 402 insufficient_credits quando o saldo próprio de quem executa não cobre a taxa. O espaço de trabalho continua pagando a execução em si.

A taxa é liquidada quando a execução termina, e só é cobrado o que o pagador tem naquele momento. Isso é no máximo o saldo de quem executa, que nunca fica abaixo de zero por causa da taxa, ou no máximo a margem disponível do orçamento do espaço de trabalho. O criador recebe exatamente o valor cobrado. O restante não é cobrado de ninguém nem pago a ninguém. O registro de ganhos do criador guarda a taxa pedida (flatFee, percentFee) ao lado do que foi cobrado (totalEarned). Veja Espaços de trabalho.

Depois, consulte a execução periodicamente:

curl https://app.nodaro.ai/v1/app/<slug>/runs/<runId> \
  -H "Authorization: Bearer $NODARO_API_TOKEN"
{
  "id": "run-uuid",
  "executionId": "exec-uuid",
  "status": "pending|running|completed|failed",
  "creditsUsed": 0,                          // the run's total, every attempt included
  "thumbnailUrl": null,                       // set when the run completes
  "execution": {
    "status": "pending|running|completed|failed",
    "nodeStates": {
      "node-abc": {
        "status": "completed",
        "output": {                           // the shape depends on the node's outputType
          "url": "https://.../result.png",
          "imageUrl": "...",
          "videoUrl": "...",
          "audioUrl": "...",
          "resultUrl": "...",
          "text": "..."
        }
      }
    },
    "totalNodes": 5,
    "completedNodes": 5,
    "failedNodes": 0,
    "totalCreditsUsed": 5,                    // this attempt's own
    "errorMessage": null,
    "completedAt": "2026-05-07T..."
  }
}
  • Consulte periodicamente, mais ou menos a cada 2 segundos. Pare quando execution.status for completed ou failed.
  • Mostre o progresso como completedNodes de totalNodes enquanto a execução estiver em andamento.
  • Em caso de falha, mostre execution.errorMessage.

O dono de uma execução pode alterar só o name, o inputValues, o hiddenNodes e o nodeStates dela, com PATCH /v1/app/{slug}/runs/{runId}. O servidor ignora todos os outros campos, e um PATCH que não indica nenhum desses quatro responde 400 bad_request.

As visões da execução trazem as suas próprias edições dos resultados dela em nodeStateEdits, o mapa que o PATCH define com nodeStates. O PATCH substitui esse mapa inteiro. Envie todas as edições já guardadas, mescladas com as suas, ou as edições que você deixar de fora se perdem.

Etapa 5: mostrar o resultado

O resultado principal é a saída do nó indicado por thumbnailNodeId. Leia a URL dele em execution.nodeStates[thumbnailNodeId].output, tentando estas chaves nesta ordem: url, imageUrl, videoUrl, audioUrl, resultUrl e, por fim, text para um resultado de texto, que você mostra como texto e não como link.

Renderize o resultado de acordo com o outputType do nó, vindo de GET /v1/nodes/{type}:

outputTypeRenderize como
imageUma imagem
videoUm player de vídeo com controles
audioUm player de áudio com controles
textTexto pré-formatado ou Markdown
dataUm visualizador de JSON, ou dados opacos

Quando thumbnailNodeId for null, use o último nó na ordem do workflow, ou mostre todas as saídas que não estejam vazias.

Renderizar a final de uma execução

Quando a renderização de um Aplicar EDL de um app faz uma prévia, a página do app oferece a Renderização final nela. Pelo código, envie POST /v1/app/{slug}/runs/{runId}/render-final com { "renderNodeId": "<render node id>" }. O servidor renderiza essa renderização em Final somente nesta execução e depois executa todos os nós após ela, uma vez. Nada antes da renderização é executado ou cobrado de novo.

A resposta é 202 com { executionId, runId, status: "pending" }. Um cabeçalho Idempotency-Key com 8 caracteres ou mais faz uma nova tentativa da mesma requisição responder 200 com "deduped": true, sem iniciar nada.

  • Quem paga. A final é cobrada de quem executa o app, pelos preços dos próprios nós, como uma segunda execução fora da execução do app. A taxa do criador do app não se aplica. A final não adiciona uma linha ao histórico de execuções e não conta para o limite diário de execuções do app.
  • A sua revisão conta. Uma revisão do Plano de edição guardada na execução com o PATCH acima é aplicada à final.
  • Onde os resultados aparecem. Quando a final tem resultados, GET /v1/app/{slug}/runs/{runId} os mostra em execution.nodeStates, por cima dos estados da prévia, e marca cada um com "fromRenderFinal": true. A execução também traz finalExecution: { id, status, completedNodes, totalNodes, errorMessage, completedAt, creditsUsed }, ou null quando nenhuma final foi pedida. O creditsUsed da própria execução continua sendo o da execução do app.
  • Um nó Enxugar episódio é finalizado da mesma forma. Um nó Enxugar episódio com Revisar antes de renderizar ativado guarda a própria prévia, então informe o próprio nó como renderNodeId. A final renderiza o episódio em qualidade final com a sua revisão da edição dele e depois adiciona as legendas e a trilha musical de fundo, sem a taxa do Enxugar episódio. Os nós depois dele já foram executados sobre a prévia na execução do app e são executados de novo na final. Só uma tentativa de prévia é finalizada: uma tentativa que já é final, ou uma que foi executada uma vez por item de lista, é recusada com render_final_not_preview.
  • Uma final que falhou não aparece. finalExecution informa o status e o errorMessage dela, e as visões mostram a prévia de novo.
StatusCódigoSignificado
400not_a_renderrenderNodeId não é um nó de renderização do app.
400preview_render_nestedO app é um componente.
402insufficient_app_creditsOs seus créditos não cobrem a final.
404not_foundNão existe essa execução sua neste app.
409continuation_not_completedA execução é um rascunho sem execução ainda, ou não foi concluída.
409already_runningUma final desta execução ainda está renderizando. O id dela está em executionId.
503run_finals_unavailableNão foi possível ler as finais anteriores da execução agora. Tente de novo: nada foi iniciado.

Cada recusa acontece antes de qualquer coisa ser gravada ou cobrada.

Tentar novamente uma execução que falhou

Uma execução de app que falhou é continuada de onde parou, não começada de novo. Envie POST /v1/app/{slug}/runs/{runId}/resume. É o botão Tentar novamente da página do app. Só as etapas que a execução não concluiu são executadas de novo. Cada etapa que ela concluiu repassa o resultado, e não é cobrada de novo. Um Clipe UGC que falhou renderiza só os clipes que não terminou.

  1. Envie { "dryRun": true, "version": <n> } antes. A resposta é 200 com steps (as etapas executadas de novo), estimatedCredits (o que se espera que o Tentar novamente cobre, com a taxa do criador incluída), reusedClips, sufficient e available. sufficient diz se o seu saldo e os seus créditos de app cobrem o Tentar novamente. appCreditsAllowance só aparece quando são os seus créditos de app que o impedem: nesse caso, o Tentar novamente seria recusado com insufficient_app_credits. Nada começa.
  2. Mostre as etapas e o preço ao usuário.
  3. Envie o mesmo corpo sem dryRun quando o usuário concordar. A resposta é 202 com { executionId, runId, status: "pending", nodeIds }. Consulte a execução periodicamente como na Etapa 4.
  • A versão e as entradas da própria execução. O Tentar novamente executa a versão do app que a execução executou, com as entradas que a execução aplicou. Ele não recebe entradas próprias. Envie "version" com a versão que a sua interface executa. Sem ela, é usada a versão mais recente do app.
  • Começar de novo, em vez disso. Para executar com outras entradas ou na versão atual do app, comece a execução de novo: POST /v1/app/{slug}/run com "runId": "<runId>". Todas as etapas são executadas de novo e cobradas de novo.
  • Um Tentar novamente de cada vez. Apertar duas vezes ao mesmo tempo inicia um só Tentar novamente: a segunda resposta é 200 com "deduped": true. Apertar enquanto esse Tentar novamente está pendente responde 409 already_running, que o indica. Um Tentar novamente de um Tentar novamente continua do que o mais recente concluiu.
  • A taxa do criador é liquidada uma vez, sobre o que o Tentar novamente executa. Como uma execução de app, o Tentar novamente usa os créditos de app de quem executa.
  • Créditos entre tentativas. O creditsUsed da execução é o total dela em todas as tentativas: o que a execução que falhou gastou mais o que cada Tentar novamente gastou. Ele se mantém atualizado enquanto um Tentar novamente roda. execution.totalCreditsUsed é só o gasto da tentativa atual. Começar a execução de novo inicia um novo total.
  • As análises contam uma execução uma vez. Nas análises do app, uma execução conta pelo resultado da sua última tentativa concluída. Uma execução que falhou e depois foi concluída com o Tentar novamente é uma execução bem-sucedida. Um Tentar novamente não acrescenta execução. Os créditos de cada tentativa contam no dia em que essa tentativa terminou.
  • Pelo SDK, pela CLI e pelo MCP. O SDK chama o Tentar novamente como client.apps.resume, a CLI como nodaro apps run-retry, e o servidor MCP como retry_app_run.
StatusCódigoSignificado
400validation_errorUm ID de execução ou um corpo malformado, ou a execução de um componente. A execução de um componente é continuada pela execução que o chamou.
400continuation_workflow_mismatch / continuation_version_mismatchA execução por trás rodou outro workflow, ou outra versão dele. Isso é raro. Comece a execução de novo.
400locked_fieldUma entrada que a execução aplicou define um campo que o app não deixa quem executa definir.
400preview_review_requiredO Tentar novamente pararia em uma prévia sem a marca da página do app.
402insufficient_app_credits / insufficient_creditsOs créditos de app ou o saldo de quem executa não cobrem o Tentar novamente.
404not_foundNão existe essa execução sua neste app.
404continuation_not_foundA execução por trás da execução de app não é sua.
409app_run_version_unavailableA versão que a execução executou não está mais disponível. Comece a execução de novo.
409app_run_version_changedO app está em outra versão que não a da execução (appVersion, runVersion). Comece a execução de novo, ou envie a versão da execução.
409continuation_not_failedA execução não falhou: ela foi concluída, ou foi interrompida. Comece de novo.
409already_runningA execução ainda está em andamento (executionId), ou foi iniciada de novo em outro lugar.
409continuation_subset_requiredTodas as etapas da execução foram concluídas. Não há nada a tentar de novo. O status é 400 quando o app não executa nenhuma etapa.
503billing_unavailableA cobrança está indisponível por um momento para uma execução de espaço de trabalho. Tente de novo em breve.

Quando um Tentar novamente é recusado com um 409, ofereça começar a execução de novo.

Excluir uma execução

curl -X DELETE https://app.nodaro.ai/v1/app/<slug>/runs/<runId> \
  -H "Authorization: Bearer $NODARO_API_TOKEN"

Uma exclusão move a execução para os itens arquivados do usuário e responde { "success": true, "archived": true }. Nada é destruído: uma automação que exclua a execução errada não consegue perder os dados do usuário. Restaurar uma execução e excluí-la de vez só são possíveis no app do Nodaro, então a sua integração não deve tentar nenhuma das duas coisas.

Autenticação

Toda execução precisa de um token bearer. Escolha o tipo de acordo com quem deve ser dono das execuções e pagar por elas:

Você está criandoUse
Uma ferramenta pessoal, um painel de agência ou uma automação internaUm token de API pessoal.
Um SaaS em que os clientes conectam as próprias contas do NodaroOAuth.
Uma ferramenta pública que executa um app para visitantes anônimosUm token de API pessoal. Quem paga é você, então limite as execuções por visitante do seu lado.

Token de API pessoal. A sua conta é dona de todas as execuções e paga por elas. Crie o token em Configurações › Tokens de API com Criar token, copie-o uma vez e guarde-o como um segredo do servidor. Ele vale até você revogá-lo. Veja Autenticação.

OAuth. A conta de cada usuário é dona das execuções dele e paga por elas. Registre um app de desenvolvedor e envie o usuário à tela de consentimento com os escopos workflows:execute e jobs:read. workflows:execute inicia execuções, tenta de novo, renderiza a versão final delas e as renomeia ou exclui. jobs:read consulta uma execução e lista execuções, e workflows:execute ou assets:read sozinhos também são aceitos para isso. Carregar o app com GET /v1/app/{slug} não exige escopo. No seu servidor, troque o código por um token de acesso que vale 90 dias. Se uma chamada responder 403 insufficient_scope, envie o usuário de novo pela tela de consentimento com os escopos mais amplos.

Manter o token no seu servidor

O token nunca deve chegar ao navegador. Os bundlers embutem toda variável de ambiente com prefixo VITE_ ou NEXT_PUBLIC_ no JavaScript que entregam, onde qualquer pessoa com as ferramentas de desenvolvedor pode lê-la e gastar os seus créditos.

[Browser]  --HTTPS-->  [Your server or edge function]  --HTTPS-->  Nodaro API
                         (holds NODARO_API_TOKEN)
Pilha de tecnologiaOnde o token fica
Lovable com SupabaseUm segredo de Edge Function do Supabase: supabase secrets set NODARO_API_TOKEN=...
Next.jsUm route handler de servidor, com process.env.NODARO_API_TOKEN e sem o prefixo NEXT_PUBLIC_
SvelteKit, Remix, NuxtUma variável de ambiente só do servidor, como $env/static/private no SvelteKit
Edge Function da Vercel ou da NetlifyUma variável de ambiente do projeto que não é exposta ao cliente
Cloudflare WorkerUm segredo do Worker: wrangler secret put NODARO_API_TOKEN

Como o código no navegador só se comunica com o seu próprio servidor, você não precisa adicionar o seu domínio às origens permitidas do Nodaro. Se você chamar o Nodaro direto do navegador com OAuth, registre a sua origem em Origens permitidas, no app de desenvolvedor.

Erros

Os erros têm o formato { "error": { "code": "...", "message": "..." } }.

StatusCódigoCausaO que fazer
400validation_errorUm inputOverrides malformado, um valor fora de allowedValues ou da lista permitida de um seletor, ou um slug malformado.Corrija o corpo da requisição.
400input_too_longUma entrada de texto é maior que o maxLength do campo.Encurte o texto até o limite que o item declara.
400locked_fieldUma substituição indica o destino de um nó externo, como o endereço de uma Saída de webhook, ou um campo que um nó UGC não aceita de uma execução.Remova a substituição. O app decide para onde envia e de onde busca, e um nó UGC só aceita os campos do cartão do criador e a duração do vídeo.
400ugc_photo_requiredUm Criador UGC está configurado como Minha foto, e a execução não envia uma foto da própria pessoa que executa.Peça a foto de quem executa, ou mude o cartão para Criador de IA.
400clone_recordings_requiredUm nó Texto para fala ou Texto para diálogo clona uma voz com o Gemini 3.8 Flash, e a execução não traz gravações da própria pessoa que executa.Peça as duas gravações WAV de quem executa: inputOverrides[<node>].replica, ou os speakers dele em um diálogo.
400clone_consent_requiredO consentimento da voz clonada não é o registro da própria pessoa que executa para essas gravações.Peça a quem executa que dê o consentimento com POST /v1/voice-clone/consent e passe o registro como replicaConsent.
400clone_model_unsupportedO modelo que a execução usa para uma voz clonada não consegue clonar uma voz. Isso acontece com um cartão de modelo exposto ou com a voz de um Personagem conectado.Mantenha o nó no Gemini 3.8 Flash.
400clone_not_fillableO app clona uma voz dentro de um sub-workflow ou de um componente, onde as gravações de quem executa não chegam.Mova o nó que clona a voz para o workflow do próprio app.
401unauthorizedO token está ausente, expirado ou revogado.Crie um novo token, ou autorize de novo.
402insufficient_app_creditsA conta por trás do token tem créditos insuficientes.Adicione créditos ou mude de plano.
402insufficient_creditsUm app que faz um vídeo UGC: o saldo não cobre o que o vídeo pode exigir enquanto os clipes dele são renderizados.Adicione créditos ou faça um vídeo mais curto.
402insufficient_creditsUm app com taxa do criador: o saldo não cobre o preço de execução anunciado do app com a taxa. Em uma execução de espaço de trabalho de um app que a organização não aprovou, o saldo próprio de quem executa não cobre a taxa. A execução do próprio criador não é conferida.Adicione créditos.
402budget_exceededUma execução de espaço de trabalho de um app com taxa do criador que a organização aprovou: o orçamento do espaço de trabalho não cobre o preço de execução anunciado do app com a taxa.Peça mais margem a um administrador do espaço de trabalho.
403insufficient_scopeFalta ao token OAuth um escopo, indicado em missingScope.Autorize de novo com os escopos mais amplos.
404not_foundO slug ou a execução não existe, o app está desativado, ou a execução registrada não pertence ao dono da execução.Confira o slug e mostre “App indisponível”.
429rate_limit_exceededO limite diário de execuções do app por usuário foi atingido.Mostre “Limite diário atingido”.
500internal_errorUma falha no servidor.Tente de novo uma vez depois de uma pausa, e relate o problema se ele persistir.

Templates de referência

Uma Edge Function do Supabase que faz proxy do app

// supabase/functions/nodaro-run/index.ts
import { serve } from "https://deno.land/std@0.224.0/http/server.ts"

const BASE = Deno.env.get("NODARO_BASE_URL")!       // for example https://app.nodaro.ai
const TOKEN = Deno.env.get("NODARO_API_TOKEN")!     // ndr_...
const SLUG = Deno.env.get("NODARO_APP_SLUG")!       // my-cool-app

serve(async (req) => {
  const url = new URL(req.url)

  // Public probe: no token is sent, because the endpoint is public.
  if (req.method === "GET" && url.pathname.endsWith("/schema")) {
    const r = await fetch(`${BASE}/v1/app/${SLUG}`)
    return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
  }

  // Start a run.
  if (req.method === "POST" && url.pathname.endsWith("/run")) {
    const { inputs } = await req.json()
    const r = await fetch(`${BASE}/v1/app/${SLUG}/run`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ inputOverrides: inputs }),
    })
    return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
  }

  // Poll a run.
  const m = url.pathname.match(/\/runs\/([0-9a-f-]{36})$/)
  if (req.method === "GET" && m) {
    const r = await fetch(`${BASE}/v1/app/${SLUG}/runs/${m[1]}`, {
      headers: { "Authorization": `Bearer ${TOKEN}` },
    })
    return new Response(await r.text(), { status: r.status, headers: { "content-type": "application/json" } })
  }

  return new Response("Not found", { status: 404 })
})

Código do navegador: ler, executar, consultar periodicamente

// 1. On mount: read the schema and build the form (steps 1 to 3).
const schema = await fetch("/functions/v1/nodaro-run/schema").then((r) => r.json())
const inputItems = schema.snapshotSettings?.presentationSettings?.inputItems ?? []

// 2. On submit: send the values keyed by node id.
const start = await fetch("/functions/v1/nodaro-run/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    inputs: { "node-abc": { prompt: form.prompt, aspectRatio: form.aspectRatio } },
  }),
}).then((r) => r.json())

// 3. Poll every 2 seconds until the run ends.
let last = start
while (last.status !== "completed" && last.execution?.status !== "completed"
       && last.status !== "failed" && last.execution?.status !== "failed") {
  await new Promise((res) => setTimeout(res, 2000))
  last = await fetch(`/functions/v1/nodaro-run/runs/${start.runId}`).then((r) => r.json())
}

// 4. Read the result.
const out = last.execution?.nodeStates?.[schema.thumbnailNodeId]?.output ?? {}
const heroUrl = out.url ?? out.imageUrl ?? out.videoUrl ?? out.audioUrl ?? out.resultUrl
const heroText = out.text

Neste template, o navegador envia valores com o id do nó como chave, e a função os repassa como inputOverrides.

Checklist antes de gerar o código da interface

  • GET {BASE}/v1/app/{slug} retornou o schema de entrada e os valores padrão.
  • Para cada nodeId em inputItems, você sabe o type dele a partir de snapshotNodes.
  • Para cada tipo de nó, GET {BASE}/v1/nodes/{type} informou a categoria, o outputType e os modelos dele.
  • Você montou a lista de campos do formulário com as regras da etapa 2.
  • Você sabe qual é o nó do resultado, thumbnailNodeId ou o último nó, e o outputType dele.
  • Você tem um token de API pessoal ou as credenciais de um app de desenvolvedor.
  • O segredo fica no seu servidor.

Perguntas frequentes

Como incorporo um miniapp do Nodaro no meu site?

Abra Miniapps, escolha Meus miniapps e clique em Incorporar no card do app. Adicione o domínio do seu site em Domínios permitidos para incorporação, clique em Copiar código de incorporação e cole o iframe na sua página. A incorporação fica bloqueada até que pelo menos um domínio seja adicionado.

De quais endpoints preciso para criar minha própria interface de miniapp?

GET /v1/app/{slug} e GET /v1/nodes/{type} para conhecer as entradas, os dois públicos. Depois, POST /v1/app/{slug}/run para iniciar uma execução e GET /v1/app/{slug}/runs/{runId} para consultá-la periodicamente, os dois com um token.

O Nodaro chama o meu servidor quando a execução de um miniapp termina?

Não. Uma execução de miniapp não faz callback. Consulte a execução periodicamente, mais ou menos a cada 2 segundos, até o status dela ser completed ou failed.

Quem paga pelas execuções de um miniapp incorporado?

A conta em nome da qual a execução é feita. Com um token de API pessoal, a sua conta paga por todas as execuções. Com OAuth, a conta de cada usuário paga pelas execuções dele.

Posso excluir a execução de um miniapp pela API?

Sim. Um DELETE na execução a arquiva, e o usuário pode recuperá-la no app do Nodaro. Restaurar e excluir de vez só são possíveis no app do Nodaro.

Última atualização

Nesta página