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ção | Sua própria interface | |
|---|---|---|
| Esforço | Colar uma tag iframe. | Criar um formulário e uma pequena rota de servidor. |
| Visual | A visualização de app do Nodaro. | O seu próprio design. |
| Em nome de quem a execução é feita | De 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 base | https://app.nodaro.ai no Nodaro Cloud, ou o endereço da sua própria instalação. |
| Identificador do app | O 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ção | Assí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.
type | Renderize como |
|---|---|
field | Um campo de formulário. Leia nodeId, field, o allowedValues opcional e o maxLength opcional, o limite de caracteres de uma entrada de texto. |
node | O 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. |
output | Uma prévia ao vivo de um resultado. Ignore-a enquanto monta o formulário e mostre-a depois da execução. |
richtext | Markdown estático que o publicador escreveu. Renderize-o como está. |
group | Um 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:
- O item de entrada tem
allowedValues: um select com essas opções. - O valor atual em
snapshotNodes[i].data[field]é um booleano: uma chave liga/desliga. - O valor atual é um número: um campo numérico, ou um controle deslizante quando o nome do campo termina em
duration,intensity,strength,scaleoutemperature. - O valor atual é uma string, e o nome do campo é
prompt,description,text,content,captionoumessage: uma área de texto com várias linhas. - 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. - Qualquer outra coisa: um campo de texto de uma linha.
Estes nomes de campo cobrem a maioria dos campos expostos:
| Nome do campo | Controle | Observações |
|---|---|---|
prompt, negativePrompt, text, description | Área de texto | |
model, provider, voice, style, tone | Lista suspensa | As opções vêm de allowedValues ou de providers. |
aspectRatio | Lista suspensa | Normalmente 1:1, 16:9, 9:16, 4:3 e 3:4. |
resolution | Lista suspensa | Normalmente 1K, 2K e 4K, ou 720p, 1080p e 4k. |
quality | Lista suspensa | Normalmente medium e high. |
duration, nFrames, seed, temperature | Número | |
enableTranslation, addAudio, headless, loop | Chave liga/desliga | |
imageUrl, videoUrl, audioUrl, referenceImage | URL | Faç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,durationoudraft. Envie o valor eminputOverrides[nodeId][field], no tipo que o nó guarda:8para uma duração, não"8", etruepara 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 comallowedValues. - 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_inputsdo MCP lista os valores de cada modelo para um campo assim, esnapshotNodes[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 slot | Controle | Valor a enviar |
|---|---|---|
| Uma cor, como um array RGBA de números de 0 a 1 | Seletor de cor | Uma string hexadecimal, como "#00ff00" |
| Uma string | Campo de texto | A string |
| Um número | Slider | O 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
httpouhttpspara 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 com400 locked_fieldantes 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 campoyoutubeUrldo 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
rightsConfirmationIddo nó eminputOverrides, dePOST /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, ouphoto.genderéwomanouman.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 com400 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 com400 input_too_long. Coloquemaxlengthna á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 usapickerAllowedValues, e um seletor de várias dimensões usapickerAllowedValuesByField({ field: [ids] }). Um valor fora da lista é recusado com400 validation_errorem 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. QuandoperMinuteCreditsouperItemCreditsnã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.estimatedCreditsinclui qualquer renderização final, erunEstimatedCredits, com as partes por minuto e por item, é só a execução. QuandomaxEstimatedCreditsestá 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 camposmax*até ser publicada de novo. QuandoestimatedCreditsIsEstimateé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ão5. - Mostre o limite diário quando
maxRunsPerUserPerDayestiver definido, como “2 de 5 execuções usadas hoje”, para evitar um429inesperado.
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 corpo | O que faz |
|---|---|
version | Executa uma versão específica do app. O padrão é a mais recente. |
inputs | As 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. |
runId | Vincula 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_exceededdo 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_creditsquando 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.statusforcompletedoufailed. - Mostre o progresso como
completedNodesdetotalNodesenquanto 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}:
outputType | Renderize como |
|---|---|
image | Uma imagem |
video | Um player de vídeo com controles |
audio | Um player de áudio com controles |
text | Texto pré-formatado ou Markdown |
data | Um 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
PATCHacima é aplicada à final. - Onde os resultados aparecem. Quando a final tem resultados,
GET /v1/app/{slug}/runs/{runId}os mostra emexecution.nodeStates, por cima dos estados da prévia, e marca cada um com"fromRenderFinal": true. A execução também trazfinalExecution: { id, status, completedNodes, totalNodes, errorMessage, completedAt, creditsUsed }, ounullquando nenhuma final foi pedida. OcreditsUsedda 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 comrender_final_not_preview. - Uma final que falhou não aparece.
finalExecutioninforma ostatuse oerrorMessagedela, e as visões mostram a prévia de novo.
| Status | Código | Significado |
|---|---|---|
| 400 | not_a_render | renderNodeId não é um nó de renderização do app. |
| 400 | preview_render_nested | O app é um componente. |
| 402 | insufficient_app_credits | Os seus créditos não cobrem a final. |
| 404 | not_found | Não existe essa execução sua neste app. |
| 409 | continuation_not_completed | A execução é um rascunho sem execução ainda, ou não foi concluída. |
| 409 | already_running | Uma final desta execução ainda está renderizando. O id dela está em executionId. |
| 503 | run_finals_unavailable | Nã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.
- Envie
{ "dryRun": true, "version": <n> }antes. A resposta é200comsteps(as etapas executadas de novo),estimatedCredits(o que se espera que o Tentar novamente cobre, com a taxa do criador incluída),reusedClips,sufficienteavailable.sufficientdiz se o seu saldo e os seus créditos de app cobrem o Tentar novamente.appCreditsAllowancesó aparece quando são os seus créditos de app que o impedem: nesse caso, o Tentar novamente seria recusado cominsufficient_app_credits. Nada começa. - Mostre as etapas e o preço ao usuário.
- Envie o mesmo corpo sem
dryRunquando o usuário concordar. A resposta é202com{ 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}/runcom"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 é
200com"deduped": true. Apertar enquanto esse Tentar novamente está pendente responde409 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
creditsUsedda 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 comonodaro apps run-retry, e o servidor MCP comoretry_app_run.
| Status | Código | Significado |
|---|---|---|
| 400 | validation_error | Um 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. |
| 400 | continuation_workflow_mismatch / continuation_version_mismatch | A execução por trás rodou outro workflow, ou outra versão dele. Isso é raro. Comece a execução de novo. |
| 400 | locked_field | Uma entrada que a execução aplicou define um campo que o app não deixa quem executa definir. |
| 400 | preview_review_required | O Tentar novamente pararia em uma prévia sem a marca da página do app. |
| 402 | insufficient_app_credits / insufficient_credits | Os créditos de app ou o saldo de quem executa não cobrem o Tentar novamente. |
| 404 | not_found | Não existe essa execução sua neste app. |
| 404 | continuation_not_found | A execução por trás da execução de app não é sua. |
| 409 | app_run_version_unavailable | A versão que a execução executou não está mais disponível. Comece a execução de novo. |
| 409 | app_run_version_changed | O 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. |
| 409 | continuation_not_failed | A execução não falhou: ela foi concluída, ou foi interrompida. Comece de novo. |
| 409 | already_running | A execução ainda está em andamento (executionId), ou foi iniciada de novo em outro lugar. |
| 409 | continuation_subset_required | Todas 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. |
| 503 | billing_unavailable | A 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á criando | Use |
|---|---|
| Uma ferramenta pessoal, um painel de agência ou uma automação interna | Um token de API pessoal. |
| Um SaaS em que os clientes conectam as próprias contas do Nodaro | OAuth. |
| Uma ferramenta pública que executa um app para visitantes anônimos | Um 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 tecnologia | Onde o token fica |
|---|---|
| Lovable com Supabase | Um segredo de Edge Function do Supabase: supabase secrets set NODARO_API_TOKEN=... |
| Next.js | Um route handler de servidor, com process.env.NODARO_API_TOKEN e sem o prefixo NEXT_PUBLIC_ |
| SvelteKit, Remix, Nuxt | Uma variável de ambiente só do servidor, como $env/static/private no SvelteKit |
| Edge Function da Vercel ou da Netlify | Uma variável de ambiente do projeto que não é exposta ao cliente |
| Cloudflare Worker | Um 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": "..." } }.
| Status | Código | Causa | O que fazer |
|---|---|---|---|
400 | validation_error | Um inputOverrides malformado, um valor fora de allowedValues ou da lista permitida de um seletor, ou um slug malformado. | Corrija o corpo da requisição. |
400 | input_too_long | Uma entrada de texto é maior que o maxLength do campo. | Encurte o texto até o limite que o item declara. |
400 | locked_field | Uma 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. |
400 | ugc_photo_required | Um 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. |
400 | clone_recordings_required | Um 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. |
400 | clone_consent_required | O 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. |
400 | clone_model_unsupported | O 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. |
400 | clone_not_fillable | O 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. |
401 | unauthorized | O token está ausente, expirado ou revogado. | Crie um novo token, ou autorize de novo. |
402 | insufficient_app_credits | A conta por trás do token tem créditos insuficientes. | Adicione créditos ou mude de plano. |
402 | insufficient_credits | Um 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. |
402 | insufficient_credits | Um 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. |
402 | budget_exceeded | Uma 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. |
403 | insufficient_scope | Falta ao token OAuth um escopo, indicado em missingScope. | Autorize de novo com os escopos mais amplos. |
404 | not_found | O 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”. |
429 | rate_limit_exceeded | O limite diário de execuções do app por usuário foi atingido. | Mostre “Limite diário atingido”. |
500 | internal_error | Uma 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.textNeste 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
nodeIdeminputItems, você sabe otypedele a partir desnapshotNodes. - Para cada tipo de nó,
GET {BASE}/v1/nodes/{type}informou a categoria, ooutputTypee 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,
thumbnailNodeIdou o último nó, e ooutputTypedele. - 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.
Páginas relacionadas
Incorporações
Apps (miniapps)
Apps OAuth
Autenticação
SDK para TypeScript
Última atualização
Incorporações
As duas formas de levar o Nodaro ao seu produto: um miniapp que executa um workflow publicado e o viewport de cena 3D sem estado, e quando usar cada uma.
Incorporar o viewport de cena 3D
Incorpore o viewport de cena 3D do Nodaro em um iframe e controle-o com postMessage: troca inicial, mensagens de estado, eventos de edição, recursos e limites.