Apps e templates
Explore e execute apps publicados do Nodaro em TypeScript, leia o histórico de execuções, clone templates de workflow em um projeto e liste os tutoriais.
client.apps explora e executa apps publicados: workflows envolvidos em um formulário simples de entradas e saídas. client.templates explora o marketplace de templates e clona um template em um dos seus projetos, e client.tutorials lista os vídeos e os workflows de tutorial. Veja Apps e Tutoriais e templates para os conceitos.
Métodos
| Método | O que faz |
|---|---|
apps.list(params?) | Explora os apps publicados |
apps.get(slug) | Lê um app, com as entradas e saídas dele |
apps.run(slug, inputs?, opts?) | Executa um app |
apps.listRuns(slug, params?) | Lista as suas execuções de um app |
apps.getRun(slug, runId) | Lê uma execução |
apps.resume(slug, runId, opts?) | Tenta de novo uma execução que falhou, a partir de onde ela parou |
apps.deleteRun(slug, runId) | Arquiva uma execução |
templates.browse(params?) | Explora o marketplace de templates |
templates.get(slug) | Lê um template, com o workflow dele |
templates.clone(slug, params) | Copia um template para um projeto |
tutorials.list() | Lista os tutoriais por categoria |
client.apps
list() e get() são públicos. run() e o histórico de execuções agem como o usuário conectado que faz a chamada.
apps.list(params?)
Explora os apps publicados, uma página por vez.
list(params?: { search?: string; category?: string; limit?: number; cursor?: string }): Promise<{
data: PublishedApp[]
nextCursor?: string | null
}>Propriedade
Tipo
const { data: apps, nextCursor } = await client.apps.list({ search: "headshot", limit: 20 })O método chama GET /v1/apps/browse. Em uma implantação que oculta a página de apps (nav.hide indica apps), a listagem não traz nenhum app: { data: [], nextCursor: null }. Uma implantação também pode desativar os trabalhos públicos (outputs.allowPublic: false). Nela, o marketplace não lista nada: { data: [], nextCursor: null }. Além disso, um app é só de quem o criou: get(), run() e resume() do app de outra pessoa lançam NotFoundError, como para um app que não existe. As suas execuções anteriores dele continuam legíveis com listRuns() e getRun().
Um PublishedApp tem id, slug, name, description, creatorId, creatorName, thumbnailUrl, category, isFeatured, runCount, estimatedCredits, perMinuteCredits, perItemCredits, createdAt e updatedAt.
estimatedCredits é o preço anunciado do app por execução. Alguns apps têm o preço definido pela duração da gravação que recebem, como uma passagem de Plano de edição ou a renderização de um episódio inteiro. Para eles, perMinuteCredits é maior que 0, e o preço é estimatedCredits mais perMinuteCredits para cada minuto da gravação. Quando o app tem uma entrada de lista que o usuário preenche, perItemCredits é maior que 0: cada item além dos itens salvos pelo criador acrescenta esse número de créditos.
O preço anunciado é uma faixa quando uma escolha que o usuário do app pode fazer custa mais. maxEstimatedCredits, com maxPerMinuteCredits e maxPerItemCredits, é o máximo que uma execução pode custar com os campos expostos do app, dentro dos limites que o criador definiu. estimatedCredits e suas partes são as configurações salvas, o preço “a partir de”. Os campos max* só aparecem quando são diferentes. Um vídeo UGC é precificado de novo para cada combinação, então uma duração de roteiro ou um idioma que o usuário do app pode escolher conta pelo preço mais alto. Um app publicado antes de a faixa existir não tem esses campos até a próxima publicação.
estimatedCreditsIsEstimate: true marca um preço informado que inclui a estimativa de uma chamada de LLM medida. Apps, templates e tutoriais trazem esse campo. A chamada de LLM é cobrada pelo uso real por token, então mostre o preço como ≈N. O campo não aparece para um preço fixo. Uma publicação cujo workflow indica um modelo de LLM ainda sem preço é recusada com 400 validation_error e reason: "llm_model_unpriced". Veja Um modelo ainda sem preço. Uma publicação cujo vídeo UGC não pôde ser precificado, nas configurações salvas ou para uma escolha que o usuário do app pode fazer, nunca é anunciada como gratuita. Ela é recusada com 503, com o código e o reason ugc_listing_unpriced, e um choice que indica o que falhou, por exemplo "a choice its users can make (Hebrew, 60 s)". Nada é gravado, então publique de novo. Lida pelo SDK, ela é um NodaroError com esse code e esse status.
apps.get(slug)
Lê um app, com o inputSchema, os campos que os usuários finais preenchem, e outputs, o que o app retorna.
get(slug: string): Promise<{ data: PublishedAppDetail }>Propriedade
Tipo
const { data: app } = await client.apps.get("pro-headshot")
console.log(app.inputSchema, app.outputs) // outputs: [{ nodeId, label, type }]runEstimatedCredits, runPerMinuteCredits e runPerItemCredits dão o preço só da execução do app: o preço anunciado sem a parte da renderização final, que é executada e cobrada à parte. editPlanPerMinute é true quando um nó Plano de edição é cobrado por minuto iniciado da gravação, e false quando é cobrado em faixas de 15, 30, 60, 90, 120 ou 180 minutos.
apps.run(slug, inputs?, opts?)
Executa um app e retorna na hora com { executionId, status, runId? }. Consulte periodicamente client.executions.get(executionId) para obter o resultado.
run(slug: string, inputs?: Record<string, unknown>, opts?: {
inputOverrides?: Record<string, Record<string, unknown>>
}): Promise<{ executionId: string; status: "pending" | "running"; runId?: string }>Propriedade
Tipo
const { executionId } = await client.apps.run("pro-headshot", { photo: photoUrl })
// Add hidden text before the app's prompt, for this run only
await client.apps.run(
"pro-headshot",
{ photo: photoUrl },
{ inputOverrides: { n1: { promptPrefix: "Studio portrait of" } } },
)Um app que recebe um link de vídeo, por meio de um nó URL de vídeo exposto, é executado com o link como valor da entrada, por exemplo client.apps.run("clip-pack", { episode: "https://www.youtube.com/watch?v=..." }). O servidor baixa um link de post antes de o primeiro nó ser executado. Um vídeo do YouTube de 4 minutos ou mais só é baixado como um trecho que você indica com inputOverrides. Qualquer outro link da web é usado como está.
inputOverrides é uma opção avançada. Ela pode definir, por exemplo, o texto antes e depois de um nó (promptPrefix e promptSuffix). Ela não pode definir o destino de um nó de saída, como a URL de um nó Saída de webhook, uma conta de publicação ou o alvo de um scraper. Uma substituição assim é recusada com 400 locked_field.
apps.listRuns(slug, params?)
Lista as suas execuções de um app, uma página por vez.
listRuns(slug: string, params?: { limit?: number; cursor?: string }): Promise<{ data: AppRun[]; nextCursor?: string | null }>Propriedade
Tipo
const { data: runs } = await client.apps.listRuns("pro-headshot", { limit: 10 })
for (const run of runs) console.log(run.status, run.outputs)Um AppRun tem id, appSlug, executionId, status (pending, running, completed, failed ou cancelled), inputs, outputs (cada um no formato { nodeId, type, url?, text? }), startedAt e finishedAt.
apps.getRun(slug, runId)
Lê uma execução de um app.
getRun(slug: string, runId: string): Promise<{ data: AppRun }>Propriedade
Tipo
const { data: run } = await client.apps.getRun("pro-headshot", runId)apps.resume(slug, runId, opts?)
Tenta de novo uma execução que falhou, a partir de onde ela parou. É o botão Tentar novamente da página do app. Só as etapas que a execução não concluiu são executadas, e só essas são cobradas. Cada etapa que ela concluiu repassa o resultado. Um Clipe UGC que falhou renderiza só os clipes que não terminou.
resume(slug: string, runId: string, opts: { dryRun: true; version?: number }): Promise<{ data: AppRunResumePlan }>
resume(slug: string, runId: string, opts?: { dryRun?: false; version?: number }): Promise<AppRunResumeResult>Propriedade
Tipo
- 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 aceita entradas próprias.
- A simulação. Com
dryRun: true, a resposta é umAppRunResumePlan:runId,continuesExecutionId,appVersion,nodeIds,steps({ nodeId, type, label }, as etapas executadas de novo),estimatedCredits,reusedClips,sufficienteavailable.estimatedCreditsinclui a taxa do criador no app, e énullsem créditos.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. Mostre o plano antes de um Tentar novamente. - O Tentar novamente iniciado. Sem
dryRun, a resposta é{ executionId, runId, status: "pending", nodeIds, deduped? }. Consulte-o periodicamente comclient.executions.get(executionId). A execução por trás da execução de app passa a ser a do Tentar novamente, entãogetRunpassa a mostrá-la. - Um Tentar novamente de cada vez. Uma segunda chamada enquanto esse Tentar novamente está pendente lança um
AlreadyRunningErrorque indica a execução dele. Só dois toques no mesmo instante chegam ao mesmo Tentar novamente, respondidos comdeduped: true.
As recusas acontecem antes de qualquer gravação ou cobrança. O code é um dos AppRunResumeRefusalCode:
code | Lançado como | Quando |
|---|---|---|
not_found | NotFoundError | Não existe essa execução sua neste app. |
continuation_not_found | NotFoundError | A execução por trás da execução de app não é sua. |
validation_error | NodaroError (400) | Um ID de execução ou um corpo malformado, ou a execução de um componente. |
app_run_version_unavailable | NodaroError (409) | A versão que a execução executou não existe mais. Comece a execução de novo. |
app_run_version_changed | AppRunVersionChangedError | O app está em outra versão que não a da execução. Comece de novo, ou envie version: err.runVersion. |
continuation_workflow_mismatch / continuation_version_mismatch | NodaroError (400) | A execução por trás rodou outro workflow, ou outra versão dele. Comece a execução de novo. |
continuation_not_failed | NodaroError (409) | A execução foi concluída ou interrompida. Comece de novo. |
already_running | AlreadyRunningError (409, executionId) | A execução ainda está em andamento, ou um Tentar novamente dela está pendente. Acompanhe executionId. |
continuation_subset_required | NodaroError (409, ou 400) | Não sobrou nada a tentar de novo (409), ou o app não executa nenhuma etapa (400). |
locked_field | NodaroError (400) | Uma entrada que a execução aplicou define um campo que o app não deixa quem executa definir. |
preview_review_required | NodaroError (400) | O Tentar novamente pararia em uma prévia sem ninguém para revisá-la. Tente de novo pela página do app. |
insufficient_app_credits / insufficient_credits | InsufficientCreditsError | Os seus créditos de app ou o seu saldo não cobrem o Tentar novamente. O code diz qual. |
billing_unavailable | NodaroError (503) | A cobrança está indisponível por um momento para uma execução de espaço de trabalho. Tente de novo em breve. |
Para executar com outras entradas ou na versão atual do app, comece a execução de novo com apps.run. Nesse caso, todas as etapas são executadas e cobradas de novo. Veja Tentar novamente uma execução que falhou.
import { AppRunVersionChangedError } from "@nodaro/sdk/errors"
const { data: plan } = await client.apps.resume("pro-headshot", runId, { dryRun: true })
console.log(`${plan.steps.length} step(s) again, about ${plan.estimatedCredits} credits`)
try {
const { executionId } = await client.apps.resume("pro-headshot", runId)
} catch (err) {
if (err instanceof AppRunVersionChangedError && err.runVersion !== undefined) {
// Continue on the run's own version anyway, or start over with apps.run.
await client.apps.resume("pro-headshot", runId, { version: err.runVersion })
}
}apps.deleteRun(slug, runId)
Arquiva uma execução. Restaurar uma execução e excluí-la de forma permanente só é possível no app do Nodaro, então um script não consegue destruir dados.
deleteRun(slug: string, runId: string): Promise<{ success: true; archived: true }>Propriedade
Tipo
await client.apps.deleteRun("pro-headshot", runId)client.templates
O marketplace de templates, público de propósito: explore-o, leia um template com o workflow inteiro e clone-o no seu projeto sem custo.
templates.browse(params?)
Explora o marketplace, uma página por vez (GET /v1/templates/browse). Não é preciso entrar na conta.
browse(params?: BrowseTemplatesParams): Promise<{ data: TemplateBrowseCard[]; nextCursor: string | null }>Propriedade
Tipo
const page = await client.templates.browse({ sort: "popular", search: "trailer" })Em uma implantação que não permite trabalhos públicos (outputs.allowPublic: false), o marketplace não lista nada: { data: [], nextCursor: null }.
O estimatedCredits de um card é o preço anunciado do template. Quando o preço acompanha a duração da gravação que o template recebe, estimatedPerMinuteCredits é maior que 0. O preço então é estimatedCredits mais esse número de créditos para cada minuto da gravação. Caso contrário, estimatedPerMinuteCredits fica ausente ou é 0. Quando uma escolha no template pode custar mais, o card também traz maxEstimatedCredits e maxEstimatedPerMinuteCredits, o topo da faixa de preço.
A rota também aceita sort=cheapest, a ordem Menos créditos da página de templates. Ela ordena pelo preço de uma gravação de 60 minutos, do menor para o maior: estimatedCredits mais 60 vezes estimatedPerMinuteCredits. O tipo TemplateSort do SDK não inclui cheapest, então envie com client.request().
templates.get(slug)
Lê um template público com o instantâneo completo do workflow: snapshotNodes, snapshotEdges e snapshotSettings (GET /v1/templates/:slug).
get(slug: string): Promise<Template>Propriedade
Tipo
const template = await client.templates.get("noir-trailer")
console.log(template.snapshotNodes.length)Lança NotFoundError quando o slug é desconhecido ou quando o template não está listado ou está inativo. Em uma implantação que não permite trabalhos públicos, também lança NotFoundError para o template de outra pessoa listado só no marketplace. Um template do canal de tutoriais continua respondendo.
templates.clone(slug, params)
Copia um template para um dos seus projetos como um novo workflow (POST /v1/templates/:slug/clone). Não custa créditos.
clone(slug: string, params: { projectId: string; name?: string }): Promise<{ workflowId: string; projectId: string }>Propriedade
Tipo
const { workflowId } = await client.templates.clone("noir-trailer", { projectId })
await client.workflows.run(workflowId)Em uma implantação que não permite trabalhos públicos, o template de marketplace de outra pessoa responde 404 not_found. Os seus próprios templates e os templates de tutorial são clonados como antes.
client.tutorials
tutorials.list()
Lista todas as categorias de tutorial, com os vídeos e os workflows de tutorial de cada uma (GET /v1/tutorials). É público e somente leitura.
list(): Promise<{ categories: TutorialCategory[] }>const { categories } = await client.tutorials.list()
for (const category of categories) {
console.log(category.name, category.videos.length, category.flows.length)
}Cada categoria tem id, name, slug, sortOrder, videos e flows. Um vídeo tem um title, uma videoUrl e uma thumbnailUrl. Um flow é um template marcado como tutorial: tem um title, uma complexity, estimatedCredits, os tipos de nó e os modelos que usa, e um slug que você pode passar para templates.get() e templates.clone().
Perguntas frequentes
Como executar um app do Nodaro pelo código?
Chame client.apps.run com o slug do app e um objeto inputs cujas chaves correspondam aos campos de entrada do app. O método retorna um executionId; consulte client.executions.get(executionId) periodicamente para obter o resultado.
Como descobrir as entradas que um app espera?
Chame client.apps.get(slug). O inputSchema lista os campos que os usuários finais preenchem, e outputs lista o que o app retorna.
Clonar um template custa créditos?
Não. client.templates.clone copia o template para um dos seus projetos sem custo. Você só paga quando executa o novo workflow.
Como tentar de novo pelo código uma execução de app que falhou?
Chame client.apps.resume(slug, runId, { dryRun: true }) para ver as etapas e o preço, e depois chame de novo sem dryRun. Só as etapas que a execução não concluiu são executadas, e só essas são cobradas.
inputOverrides pode mudar para onde um app envia os resultados?
Não. Uma substituição não pode definir um destino, como a URL de um nó Saída de webhook ou uma conta de publicação. A execução é recusada com 400 locked_field.
Páginas relacionadas
Apps (miniapps)
Workflows e projetos
Tarefas e execuções
Tutoriais e templates
Última atualização
Executar nós
Execute qualquer nó do Nodaro em TypeScript, sem workflow: descubra os tipos, inicie execuções, aguarde resultados e passe referências e direção de câmera.
LLM e Reduce
Obtenha JSON validado de um modelo de linguagem com client.llm e use client.reduce para escolher o melhor de vários resultados, votar, juntar ou mesclar.