Tarefas e execuções
Consulte, liste, avalie, cancele e exclua execuções do Nodaro em TypeScript, acompanhe workflows e receba webhooks assinados quando uma tarefa termina.
Uma tarefa é uma única geração no Nodaro, como uma imagem, uma renderização de vídeo ou uma narração, e uma execução é cada vez que um workflow inteiro é executado. client.jobs lê, lista, cancela e exclui tarefas, e client.executions lê, lista e cancela execuções de workflows. client.webhooks registra endpoints que o Nodaro chama quando uma tarefa termina. client.videoPro interrompe ou continua uma execução longa do nó Gerar vídeo Pro. Os métodos chamam os mesmos endpoints das APIs REST de Tarefas e de Execuções.
Métodos
| Método | O que faz |
|---|---|
executions.get(id) | Lê uma execução de workflow, com o estado de cada nó |
executions.listForWorkflow(workflowId, params?) | Lista as execuções de um workflow |
executions.cancel(id, params?) | Interrompe uma execução de workflow |
jobs.get(id) | Lê uma tarefa com a entrada e a saída dela |
jobs.list(params?) | Lista as suas tarefas, das mais recentes para as mais antigas |
jobs.rate(id, rating) | Avalia uma das suas tarefas como boa ou ruim, ou limpa a avaliação |
jobs.rename(id, title) | Dá um nome a uma das suas tarefas, ou apaga o nome |
jobs.fromUpload(params) | Registra como tarefa uma imagem editada no navegador |
jobs.getStatus(id) | Lê o status de uma tarefa, para consulta periódica |
jobs.cancel(id) | Interrompe uma tarefa e reembolsa os créditos reservados |
jobs.delete(id, options?) e jobs.restore(id) | Envia uma tarefa para a Lixeira, traz de volta ou exclui permanentemente |
webhooks.create(input) e outros | Registra, altera, testa e audita os endpoints que o Nodaro chama quando uma tarefa termina |
verifyWebhookSignature(options) | Verifica a assinatura de uma chamada que o seu endpoint recebeu |
videoPro.stop(jobId) | Interrompe uma execução do Gerar vídeo Pro e mantém o que já está pronto |
videoPro.continueRun(jobId, opts?) | Continua uma execução do Gerar vídeo Pro como uma nova tarefa |
Status
Uma tarefa passa por estes status:
| Status da tarefa | Significado |
|---|---|
pending, queued | Esperando um worker. |
processing | Em execução. progress vai de 0 a 100 quando o modelo informa o progresso. |
pending_review | Retido para revisão humana por uma política de conteúdo desta implantação. Não é um estado final. |
completed | Concluído. output_data contém o resultado. |
failed | Falhou. error_message explica o motivo, e error_hint pode classificá-lo. |
cancelled | Interrompido por um cancelamento. |
Uma execução tem status próprios: pending, running, completed, failed, cancelled, stopping, timed_out e discarded. Cada nó dentro dela fica em pending, running, completed, failed ou skipped.
client.executions
Uma execução é cada vez que um workflow é executado. Ela reúne uma tarefa por nó de IA e o estado de cada nó.
executions.get(id)
Lê uma execução de workflow, incluindo um mapa com o estado de cada nó. Quando o ID pertence a uma tarefa de um único nó, e não a uma execução de workflow, o servidor responde no mesmo formato, para esse único nó.
get(id: string): Promise<{ data: WorkflowExecution }>Propriedade
Tipo
const { data } = await client.executions.get(executionId)
console.log(data.status, `${data.completedNodes}/${data.totalNodes}`, data.totalCreditsUsed)Um WorkflowExecution tem id, kind, workflowId, status, outcome, triggerType (manual, webhook, schedule, app_run, single-node, telegram, telegram_account, api ou mcp), nodeStates, totalNodes, completedNodes, failedNodes, totalCreditsUsed, errorMessage, startedAt, completedAt, createdAt e updatedAt. kind é execution para uma execução de workflow e job para uma tarefa de um único nó. Uma tarefa de um único nó iniciada por um cliente MCP tem o triggerType mcp.
Execuções que não encontram nada novo. Uma execução que não encontrou nada novo termina como completed, não como failed. Por exemplo, um feed não encontrou posts novos, então o redator depois dele não tinha nada para escrever. Um nó que precisa de texto, cujo texto conectado veio de um nó que não produziu nada nesta execução, é pulado com nodeStates[id].skipReason definido como "empty_input". A execução concluída então tem outcome: "nothing_new". Qualquer outra execução concluída tem outcome: "succeeded". outcome fica ausente até a execução terminar.
import { executionOutcome, countEmptyInputSkips } from "@nodaro/sdk"
const { data } = await client.executions.get(executionId)
if (data.outcome === "nothing_new") {
console.log(`Nothing new: ${countEmptyInputSkips(data.nodeStates)} node(s) had nothing to work on`)
}
executionOutcome(data.status, data.nodeStates) // the same answer, worked out in your codeComo ler a saída de um nó. nodeStates[nodeId].output está presente quando o nó terminou em completed. Também pode estar presente quando o nó terminou em failed, mas a execução manteve um resultado utilizável, como fazem os nós de cena 3D. Verifique o campo, não o status, e nunca trate um output presente como sucesso:
import { nodeStateMayCarryOutput } from "@nodaro/sdk"
const node = data.nodeStates["scene-1"]
if (node.status === "failed") {
console.error(node.error) // the failure stands
if (node.output?.plan) {
// the draft the run kept is still here, and it was billed
}
}
nodeStateMayCarryOutput(node.status) // true for "completed" and "failed"OUTPUT_BEARING_NODE_STATUSES, o conjunto desses dois status, também é exportado.
executions.listForWorkflow(workflowId, params?)
Lista as execuções de um workflow, das mais recentes para as mais antigas, uma página por vez. A lista inclui as execuções de um único nó iniciadas nesse workflow.
listForWorkflow(workflowId: string, params?: ListExecutionsForWorkflowParams): Promise<{
data: WorkflowExecutionSummary[]
nextCursor?: string
}>Propriedade
Tipo
const { data: runs, nextCursor } = await client.executions.listForWorkflow(workflowId, {
limit: 20,
status: "completed",
})Cada WorkflowExecutionSummary traz o mesmo kind e o mesmo outcome de get().
executions.cancel(id, params?)
Interrompe uma execução de workflow. Há três maneiras de interrompê-la:
- De imediato (o padrão): as tarefas em andamento são canceladas, os créditos reservados delas são reembolsados e o status passa a
cancelled. Uma tarefa de LLM medida em andamento também é cancelada, mas é cobrada pelo que o provedor já cobrou por ela, e o resto da reserva é reembolsado. Uma tarefa parada antes de a chamada começar é reembolsada, exceto pelo que uma tentativa anterior da mesma tarefa já usou. mode: "after_current": o status passa astopping. Os nós em andamento terminam e aparecem no canvas e na sua biblioteca, e depois a execução para.mode: "discard": nenhum nó novo começa, mas as tarefas em andamento não são canceladas, porque não dá para interromper no meio a chamada a um modelo externo. Elas terminam e são salvas na sua biblioteca, mas os resultados não voltam para o canvas. O status passa adiscarded, e não há reembolso, porque as tarefas foram concluídas.
cancel(id: string, params?: { mode?: "after_current" | "discard" }): Promise<{ success: true }>Propriedade
Tipo
await client.executions.cancel(executionId, { mode: "after_current" })client.jobs
Uma tarefa é uma única geração: uma imagem, uma renderização de vídeo, uma narração. Uma execução de workflow cria uma tarefa por nó de IA, e toda execução de um único nó cria uma tarefa. Os campos da tarefa usam snake_case, como a API os envia.
jobs.get(id)
Lê uma tarefa, incluindo a entrada e a saída dela.
get(id: string): Promise<{ data: Job }>Propriedade
Tipo
const { data: job } = await client.jobs.get(jobId)
if (job.status === "completed") console.log(job.output_data)Um Job tem estes campos:
| Campo | Descrição |
|---|---|
id, status, progress | O ID da tarefa, o status dela e o progresso, de 0 a 100. |
input_data, output_data | A requisição e o resultado. Os valores exclusivos do servidor são removidos dos dois. |
error_message | Por que a tarefa falhou, ou null. |
error_detail | As próprias palavras do provedor sobre a falha, com os links reduzidos ao host e os segredos removidos. null quando a falha não tinha nenhuma. Também é null em uma tarefa de uma execução de workflow cujo workflow você não pode abrir, como o link de compartilhamento ou o app publicado de outra pessoa que você executou. Uma implantação pode reservar essas palavras aos administradores dela, e então ele também é null. Mostre ao lado de error_message e decida o que fazer a partir de error_hint. |
error_hint | Um motivo estruturado para algumas falhas. Veja abaixo. |
credits | Os créditos reservados para a tarefa, ou null. |
credit_status | reserved, committed ou refunded: a situação dos créditos. null para uma tarefa sem cobrança. |
credits_charged | Quanto a tarefa custou depois que a reserva dela foi liquidada, incluindo as etapas que ela executou. Uma tarefa que executa outras tarefas para você, como a preparação das referências, a máscara e o vídeo de uma execução do Video Remake, é cobrada por cada etapa quando a etapa é liquidada. Pode ser menor que a reserva. Quando a reserva da própria execução foi reembolsada, é 0 mais as etapas liquidadas. É null enquanto a reserva da própria tarefa está aberta, mesmo com algumas etapas liquidadas, quando nada na execução foi reservado, ou quando as etapas não puderam ser lidas por um momento. Some este campo para totalizar o seu gasto. |
credits_held | A reserva da execução: credits mais as reservas das etapas. |
credits_released | Quanto voltou de credits_held depois que todas as reservas da execução foram liquidadas, ou null até lá. |
job_type | O tipo de tarefa. |
created_at, started_at, completed_at | Marcações de data e hora. |
user_id | O dono. |
source, source_detail | De onde a tarefa veio: sdk, cli, mcp, app, web, api e outros, com um detalhe como sdk/2.17.0. |
recovering | true enquanto a plataforma recupera uma tarefa cujo worker parou depois que o modelo entregou o resultado. |
favorited | Se o dono da tarefa a favoritou. Veja client.gallery. |
rating | "good", "bad" ou null. Veja jobs.rate(). |
title | O nome que você deu à tarefa, ou null até você dar um. Veja jobs.rename(). |
session_id | A sessão de geração em que a tarefa foi criada, ou null. |
O servidor omite favorited e rating quando não consegue lê-los por um momento. Trate um campo ausente como desconhecido, nunca como false.
O output_data de uma tarefa de imagem traz o tamanho da imagem em pixels: width e height de imageUrl, e images ({ url, width, height } por item) ao lado de imageUrls. Tarefas mais antigas não têm esses campos. Job.output_data tem o tipo unknown, então converta-o para NodeJobOutput para lê-los tipados. Veja runAndWait().
error_hint tem cinco tipos. Verifique kind antes de ler o restante:
safety-block: o filtro de segurança do próprio modelo recusou a saída.classécopyright,likenessousafety.retrieddiz se o Nodaro já tentou de novo uma vez, esuggestedProvider, quando presente, indica um modelo em que você pode repetir a mesma requisição.subject: "input_video", quando presente, significa que o provedor recusou o próprio vídeo de entrada da tarefa: envie outro clipe.subject: "input_image"em um bloqueiocopyrightsignifica que o provedor recusou uma das imagens de entrada por possível violação de direitos autorais: envie outra imagem.subject: "prompt"significa que as próprias palavras do provedor apontaram o prompt: mude o prompt.subject: "audio"significa que elas culparam o áudio gerado, e não a imagem. Veja Quando um modelo bloqueia o prompt.policy-block: uma política de conteúdo desta implantação rejeitou a requisição ou o resultado.reasonfoi escrito para os usuários, então mostre-o como está.credits: a tarefa ficou sem créditos no meio da execução, porque uma etapa que reserva os próprios créditos foi recusada, por exemplo o vídeo que uma execução do Video Remake ou de uma trend inicia.codeé o código da recusa:insufficient_credits, ou um limite do plano ou do espaço de trabalho, comofree_video_limitoubudget_exceeded. Trate um código desconhecido comoinsufficient_credits. Os créditos da tarefa são reembolsados. Peça à pessoa que faça uma recarga, ou que aumente o limite, e execute de novo.input-refused: o provedor recusou o vídeo de entrada da tarefa sem indicar uma classe de política de conteúdo.subjecté"input_video". Nenhum outro modelo é sugerido: envie outro clipe.request-refused: o provedor recusou a requisição como ela foi enviada, indicando um defeito dela, como uma configuração, o formato ou o tamanho de um arquivo, ou o comprimento do prompt. A mesma requisição é recusada de novo: mude as imagens de entrada, o vídeo, o prompt ou as configurações. Comsubject: "input_video", as palavras do provedor apontaram o vídeo de entrada como o defeito, como a duração ou o tamanho dele, ou nenhum personagem encontrado nele: envie outro clipe. Não é um bloqueio por política de conteúdo. Em uma execução do Video Remake ou de trend, é a recusa de uma etapa.
jobs.list(params?)
Lista as suas tarefas, das mais recentes para as mais antigas, uma página por vez (GET /v1/jobs).
list(params?: ListJobsParams): Promise<{
data: Job[]
next: string | null
}>Propriedade
Tipo
let cursor: string | undefined
do {
const page = await client.jobs.list({ type: "llm-structured", origin: "my-app", cursor })
for (const job of page.data) console.log(job.id, job.status)
cursor = page.next ?? undefined
} while (cursor)Todos os filtros se combinam entre si. Uma página pode ter menos linhas que limit, até nenhuma, e ainda assim ter um next. Pagine com base em next, nunca no número de linhas.
// Your favorited images and videos that came out well
const { data: keepers } = await client.jobs.list({
type: ["generate-image", "generate-video"],
status: "completed",
favorited: true,
rating: "good",
})jobs.rate(id, rating)
Avalia uma das suas tarefas como "good" ou "bad", ou limpa a avaliação com null (PUT /v1/jobs/:id/rating). Uma tarefa tem uma avaliação, e só o dono dela pode avaliá-la. A tarefa de outra pessoa lança NotFoundError.
rate(id: string, rating: "good" | "bad" | null): Promise<{ data: { jobId: string; rating: "good" | "bad" | null } }>Propriedade
Tipo
await client.jobs.rate(jobId, "good")
await client.jobs.rate(jobId, null) // clear itA avaliação volta como Job.rating e filtra jobs.list(). Apps OAuth precisam do escopo assets:write. Um servidor sem avaliações lança um NodaroError com o código not_available e o status 503.
jobs.rename(id, title)
Dá um nome a uma das suas tarefas, ou apaga o nome com null (PATCH /v1/jobs/:id). Use-o para um nome como “Wedding toast, final” (brinde do casamento, versão final) em uma imagem, um clipe, uma faixa ou uma tentativa de fala. Só o dono da tarefa pode dar um nome a ela. A tarefa de outra pessoa lança NotFoundError.
rename(id: string, title: string | null): Promise<{ data: { jobId: string; title: string | null } }>Propriedade
Tipo
await client.jobs.rename(jobId, "Hero shot v2")
await client.jobs.rename(jobId, null) // clear it- O nome perde os espaços nas pontas. Um nome longo demais ou com várias linhas lança um
NodaroErrorcom o códigovalidation_error. - Dar um nome é gratuito e funciona em qualquer tipo e status de tarefa, inclusive na Lixeira. Nada mais na tarefa muda, e os resultados mantêm a ordem.
- O nome volta como
Job.titleemget(),list(), nos itens de uma sessão e emclient.trash.list(). Ele também étitleem um cartão da galeria, público ao lado do prompt, e em uma linha da biblioteca, onde é o nome da tarefa que criou o arquivo, não o seufilename. - Apps OAuth precisam do escopo
assets:write.
jobs.fromUpload(params)
Registra como tarefa uma imagem editada no navegador (POST /v1/jobs/from-upload). Guarde antes a imagem editada com uploads.upload. O resultado é uma tarefa image-edit concluída, privada e gratuita, cujo output_data.imageUrl é o arquivo enviado. Depois disso, você pode avaliá-la, favoritá-la, listá-la com list({ type: "image-edit" }) e arquivá-la em uma sessão como qualquer tarefa de imagem.
fromUpload(params: JobFromUploadParams): Promise<{ data: Job }>Propriedade
Tipo
const upload = await client.uploads.upload(editedPng)
const { url: editStateUrl } = await client.uploads.uploadJson(designState)
const { data: job } = await client.jobs.fromUpload({
assetId: upload.assetId!,
sourceJobId,
editStateUrl,
sessionId,
})Um arquivo enviado é uma tarefa: o mesmo assetId de novo retorna a mesma tarefa, então uma nova tentativa nunca cria duas. A edição de uma imagem de personagem, objeto, criatura ou lugar mantém esse vínculo. Apps OAuth precisam do escopo assets:write.
NotFoundError: o arquivo, a origem ou a sessão não pertence a você.NodaroErrorcom o códigovalidation_error: o arquivo não é uma imagem que você guardou, ou a origem não tem uma imagem finalizada.JobBlockedError: uma política de tarefas da implantação recusa a imagem. Veja Registrar uma imagem editada no navegador.
jobs.getStatus(id)
Lê apenas o status de uma tarefa: id, status, progress, output_data, error_message, error_detail, error_hint, credit_status e completed_at, quando a tarefa terminou pelo relógio do servidor, ou null até ela terminar (GET /v1/jobs/:id/status). Deixa de fora os dados da requisição e os campos de custo, então é bem mais leve que get(). Use-o em loops de consulta periódica.
getStatus(id: string): Promise<{ data: JobStatusResult }>Propriedade
Tipo
async function waitForJob(jobId: string) {
for (;;) {
const { data } = await client.jobs.getStatus(jobId)
if (data.status === "completed") return data.output_data
if (data.status === "failed" || data.status === "cancelled") {
throw new Error(data.error_message ?? data.status)
}
await new Promise((resolve) => setTimeout(resolve, 2_000))
}
}client.nodes.runAndWait() executa esse loop por você, com progresso, cancelamento e erros tipados.
jobs.cancel(id)
Cancela uma tarefa e reembolsa os créditos que ela tinha reservado. Uma tarefa retida para revisão também pode ser cancelada.
cancel(id: string): Promise<{ success: true; cancelled: number; inFlight?: boolean }>Uma tarefa de LLM medida em andamento é a exceção. Se a chamada dela já começou, o cancelamento responde { success: true, cancelled: 0, inFlight: true }: a tarefa termina e é cobrada só pelo que usou. Uma tarefa parada antes de a chamada começar é reembolsada, exceto pelo que uma tentativa anterior da mesma tarefa já usou, por exemplo uma nova tentativa depois de uma tentativa cobrada.
Propriedade
Tipo
const { cancelled } = await client.jobs.cancel(jobId)jobs.delete(id, options?) e jobs.restore(id)
delete envia uma tarefa para a Lixeira (DELETE /v1/jobs/:id). A partir daí, todas as leituras deixam a tarefa de fora. Ela pode ser restaurada por 30 dias e depois é excluída permanentemente, com a mídia privada dela. Uma cópia salva na Biblioteca continua lá. restore (POST /v1/jobs/:id/restore) traz a tarefa de volta, para todas as sessões em que ela estava. { forever: true } exclui permanentemente, agora, uma tarefa que já está na Lixeira. Em uma tarefa ativa, ele lança um NodaroError com o código not_in_trash (status 409).
Só o dono da tarefa pode excluí-la ou restaurá-la. Uma tarefa que ainda está em andamento continua em andamento, então cancele-a antes quando o worker dela precisar parar. Nada é reembolsado. Os apps OAuth precisam do escopo assets:write. Os dois métodos retornam { success: true }.
delete(id: string, options?: { forever?: boolean }): Promise<{ success: true }>
restore(id: string): Promise<{ success: true }>Propriedade
Tipo
await client.jobs.delete(jobId) // to the Trash
await client.jobs.restore(jobId) // undo
await client.jobs.delete(jobId, { forever: true }) // after a delete: gone for goodUma tarefa excluída nunca aparece em jobs.list(): ela está em client.trash.
client.webhooks
Os webhooks de saída avisam o seu servidor quando uma tarefa termina, para que o seu app não precise consultar periodicamente. Registre um endpoint https, e o Nodaro envia a ele um POST para cada job.completed e job.failed da sua conta. Cada chamada é assinada com o segredo próprio do endpoint. As chamadas que falham são repetidas com intervalos crescentes por cerca de 43 horas, e cada tentativa fica guardada no registro de entregas do endpoint. Veja Webhooks para os eventos, o corpo, os cabeçalhos e o cronograma de novas tentativas.
Tokens de app OAuth precisam do escopo jobs:read. Um endpoint que um app conectado registra recebe só as tarefas que esse próprio app enviou.
create(input: CreateWebhookEndpointInput): Promise<CreatedWebhookEndpoint> // { data, secret }
list(): Promise<{ data: WebhookEndpoint[] }>
get(id: string): Promise<{ data: WebhookEndpoint }>
update(id: string, input: UpdateWebhookEndpointInput): Promise<{ data: WebhookEndpoint }>
delete(id: string): Promise<{ success: true }>
rotateSecret(id: string, input?: RotateWebhookSecretInput): Promise<RotatedWebhookSecret> // { secret, previousSecretExpiresAt }
deliveries(id: string, params?: ListWebhookDeliveriesParams): Promise<WebhookDeliveryPage>
getDelivery(id: string, deliveryId: string): Promise<{ data: WebhookDelivery }>
test(id: string): Promise<{ data: WebhookDelivery }>webhooks.create(input)
Registra um endpoint e o retorna com o secret dele (whsec_…). O segredo é mostrado uma única vez, então guarde-o com a configuração do seu servidor.
Propriedade
Tipo
const { data: endpoint, secret } = await client.webhooks.create({
url: "https://example.com/nodaro-webhook",
events: ["job.completed", "job.failed"],
})
await client.webhooks.test(endpoint.id) // sends a pingUm endereço pode ter um endpoint (409 url_taken). Uma conta pode ter no máximo 10 endpoints (400 limit_reached).
webhooks.update(id, input)
Altera qualquer um entre url, events, description (null a limpa) e isActive. Depois de 50 entregas seguidas falharem de vez, o Nodaro desliga o endpoint e define disabledReason como "consecutive_failures". isActive: true o liga de novo e zera consecutiveFailures.
webhooks.rotateSecret(id, input?)
Cria um novo segredo e o retorna uma única vez. O novo segredo assina todas as entregas a partir de agora, inclusive as novas tentativas. O segredo antigo continua assinando ao lado dele por gracePeriodSeconds, de 0 a 604800 (padrão de um dia), para que você atualize o seu receptor sem interrupção. Durante esse tempo, Nodaro-Signature traz um segundo v1=, e verifyWebhookSignature aceita qualquer um dos dois. Passe { gracePeriodSeconds: 0 } para desativar na hora um segredo vazado.
const { secret, previousSecretExpiresAt } = await client.webhooks.rotateSecret(endpoint.id)previousSecretExpiresAt é null quando o segredo antigo foi desativado na hora.
webhooks.deliveries(id, params?) e getDelivery(id, deliveryId)
deliveries() lê o registro de entregas, das mais novas para as mais antigas. O registro guarda 30 dias. Filtre com status ("pending", "delivered" ou "failed") e pagine com limit (de 1 a 100, padrão 20) e cursor. getDelivery() lê uma entrega pelo id dela.
Cada WebhookDelivery traz event, jobId, status, attempts, responseStatus, responseBody (os primeiros 2 KB), durationMs, error, requestBody, nextAttemptAt e deliveredAt. requestBody é o corpo exato enviado e passa a ser null quando a entrega dá certo.
webhooks.test(id)
Coloca um ping na fila e retorna a entrega dele. O ping é enviado em segundos e tentado uma vez, mesmo para um endpoint desligado. Acompanhe-o com getDelivery(id, delivery.id).
verifyWebhookSignature(options)
Verifica uma chamada que o seu endpoint recebeu e retorna o evento já interpretado. É uma exportação de nível superior de @nodaro/sdk, não um método de client. Usa só Web Crypto, então roda no Node 20+, Deno, Bun, Cloudflare Workers, Vercel Edge e navegadores.
verifyWebhookSignature(options: {
payload: string | Uint8Array | ArrayBuffer // the raw body, as received
header: string | readonly string[] | null | undefined // Nodaro-Signature
secret: string // whsec_…
toleranceSeconds?: number // default 300; 0 turns the check off
}): Promise<WebhookEvent>Passe o corpo bruto exatamente como foi recebido, nunca um JSON que você interpretou e serializou de novo. O evento é um JobWebhookEvent, cujo data.job é um Job, ou um PingWebhookEvent. Uma verificação que falha lança WebhookSignatureError com um destes códigos: missing_header, malformed_header, signature_mismatch, timestamp_outside_tolerance, invalid_payload, missing_secret ou crypto_unavailable. A comparação leva tempo constante.
import { verifyWebhookSignature, WebhookSignatureError } from "@nodaro/sdk"
export async function POST(request: Request) {
try {
const event = await verifyWebhookSignature({
payload: await request.text(),
header: request.headers.get("nodaro-signature"),
secret: process.env.NODARO_WEBHOOK_SECRET!,
})
if (event.type === "job.completed") await saveResult(event.data.job)
return new Response(null, { status: 204 })
} catch (err) {
if (err instanceof WebhookSignatureError) return new Response(err.code, { status: 400 })
throw err
}
}Responda com qualquer status 2xx em até 10 segundos, e a entrega conta como entregue. O id do corpo é o id da entrega e continua o mesmo em todas as novas tentativas, então use-o para pular um evento que você já tratou.
client.videoPro
Controle de execução para o Gerar vídeo Pro, o nó que renderiza vídeos longos em segmentos. Funciona no Nodaro Cloud. Inicie a execução como qualquer execução de nó e depois use estes métodos na tarefa dela.
videoPro.stop(jobId)
Interrompe de forma controlada uma tarefa do Gerar vídeo Pro em andamento. O segmento em andamento é abandonado e cobrado mesmo assim, e os segmentos restantes são pulados. Os segmentos concluídos são unidos no vídeo final da tarefa, e a reserva não usada é reembolsada. Uma tarefa que ainda não começou é cancelada com reembolso total.
stop(jobId: string): Promise<StopVideoProResult>Propriedade
Tipo
await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // becomes completed, with the partial videoContinue consultando a tarefa periodicamente. Ela termina com output_data.pro.stopped igual a true.
videoPro.continueRun(jobId, opts?)
Continua uma execução interrompida, com falha ou concluída como uma nova tarefa. Os segmentos anteriores a fromSegment são reaproveitados, e todos os segmentos a partir dele são gerados de novo. Você paga apenas pelos segmentos gerados de novo, mais a taxa fixa do Pro.
continueRun(jobId: string, opts?: { fromSegment?: number }): Promise<ContinueVideoProResult>Propriedade
Tipo
const { jobId: newJobId, fromSegment } = await client.videoPro.continueRun(jobId, { fromSegment: 4 })O resultado traz o novo jobId a consultar periodicamente e pode trazer continuedFromJobId, fromSegment, segmentCount e deduped.
Perguntas frequentes
Qual é a diferença entre uma tarefa e uma execução?
Uma tarefa é uma única geração, como uma imagem ou um vídeo. Uma execução é cada vez que um workflow inteiro é executado: ela reúne uma tarefa por nó de IA, mais o estado de cada nó.
Qual método um loop de consulta periódica deve chamar?
client.jobs.getStatus(jobId). Ele retorna apenas o status, o progresso, a saída e o erro, então é bem mais leve que client.jobs.get.
Cancelar uma tarefa reembolsa os créditos?
Sim. client.jobs.cancel interrompe a tarefa e reembolsa os créditos que ela tinha reservado. Cancelar uma execução de imediato faz o mesmo com as tarefas dela em andamento. Uma tarefa de LLM medida cuja chamada já começou é a exceção: ela é cobrada pelo que usou.
O Nodaro pode chamar o meu servidor quando uma tarefa termina, em vez de o meu app consultar periodicamente?
Sim. Registre um endpoint https com client.webhooks.create. O Nodaro então envia um POST assinado para cada job.completed e job.failed da sua conta. Verifique cada chamada com verifyWebhookSignature.
O que significa o status pending_review?
Uma política de conteúdo desta implantação está retendo o resultado para que uma pessoa o revise. Não é um estado final: depois, a tarefa passa a completed, failed ou cancelled. Continue esperando e não execute a requisição de novo.
Páginas relacionadas
Executar nós
Workflows e projetos
Erros
Tarefas
Webhooks
Última atualização
Workflows e projetos
Crie, atualize, compartilhe, exporte, importe e execute workflows do Nodaro em TypeScript com client.workflows e agrupe-os em projetos com client.projects.
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.