Jobs e execuções

Um job é 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 jobs, e client.executions lê, lista e cancela execuções de workflows. client.videoPro interrompe ou continua uma execução longa do nó Gerar vídeo Pro (Generate Video Pro). Os métodos chamam os mesmos endpoints das APIs REST de Jobs e de Execuções.

Métodos

Status

Um job passa por estes status:

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 um job 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 um job 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 }>

const { data } = await client.executions.get(executionId)
console.log(data.status, `${data.completedNodes}/${data.totalNodes}`, data.totalCreditsUsed)

Um WorkflowExecution tem id, workflowId, status, triggerType (manual, webhook, schedule, app_run ou single-node), nodeStates, totalNodes, completedNodes, failedNodes, totalCreditsUsed, errorMessage, startedAt, completedAt, createdAt e updatedAt.

Como 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
}>

const { data: runs, nextCursor } = await client.executions.listForWorkflow(workflowId, {
  limit: 20,
  status: "completed",
})

executions.cancel(id, params?)

Interrompe uma execução de workflow. Há três maneiras de interrompê-la:

• De imediato (o padrão): os jobs em andamento são cancelados, os créditos reservados deles são reembolsados e o status passa a cancelled.
• mode: "after_current": o status passa a stopping. 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 os jobs em andamento não são cancelados, porque não dá para interromper no meio a chamada a um modelo externo. Eles terminam e são salvos na sua biblioteca, mas os resultados não voltam para o canvas. O status passa a discarded, e não há reembolso, porque os jobs foram concluídos.

cancel(id: string, params?: { mode?: "after_current" | "discard" }): Promise<{ success: true }>

await client.executions.cancel(executionId, { mode: "after_current" })

client.jobs

Um job é uma única geração: uma imagem, uma renderização de vídeo, uma narração. Uma execução de workflow cria um job por nó de IA, e toda execução de um único nó cria um job. Os campos do job usam snake_case, como a API os envia.

jobs.get(id)

Lê um job, incluindo a entrada e a saída dele.

get(id: string): Promise<{ data: Job }>

const { data: job } = await client.jobs.get(jobId)
if (job.status === "completed") console.log(job.output_data)

Um Job tem estes campos:

error_hint tem dois 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, likeness ou safety. retried diz se o Nodaro já tentou de novo uma vez, e suggestedProvider, quando presente, indica um modelo em que você pode repetir a mesma requisição. 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. reason foi escrito para os usuários, então mostre-o como está.

jobs.list(params?)

Lista os seus jobs, dos mais recentes para os mais antigos, uma página por vez (GET /v1/jobs).

list(params?: { type?: string; origin?: string; limit?: number; cursor?: string }): Promise<{
  data: Job[]
  next: string | null
}>

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)

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.

jobs.getStatus(id)

Lê apenas o status de um job: id, status, progress, output_data, error_message, error_hint e credit_status (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 }>

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 um job e reembolsa os créditos que ele tinha reservado. Um job retido para revisão também pode ser cancelado.

cancel(id: string): Promise<{ success: true; cancelled: number }>

const { cancelled } = await client.jobs.cancel(jobId)

jobs.delete(id)

Exclui um job e a mídia privada que ele produziu (DELETE /v1/jobs/:id). Só o dono do job pode excluí-lo. Um job em andamento é excluído no estado em que está, então cancele-o antes quando o worker dele precisar parar.

delete(id: string): Promise<{ success: true }>

await client.jobs.cancel(jobId)
await client.jobs.delete(jobId)

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 no job dela.

videoPro.stop(jobId)

Interrompe de forma controlada um job 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 do job, e a reserva não usada é reembolsada. Um job que ainda não começou é cancelado com reembolso total.

stop(jobId: string): Promise<StopVideoProResult>

await client.videoPro.stop(jobId)
const { data } = await client.jobs.getStatus(jobId) // becomes completed, with the partial video

Continue consultando o job periodicamente. Ele termina com output_data.pro.stopped igual a true.

videoPro.continueRun(jobId, opts?)

Continua uma execução interrompida, com falha ou concluída como um novo job. 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>

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.