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

Mídia e uploads

Envie arquivos ao Nodaro, liste sua biblioteca, importe vídeos de links, corte clipes, embuta legendas e componha imagens e vídeos em TypeScript.

client.uploads armazena os seus arquivos no Nodaro, client.library lista as mídias que você já tem e client.gallery navega pela galeria pública e pelos seus favoritos. client.media prepara e edita mídias: baixa vídeos de links, corta clipes, embute legendas e compõe imagens e vídeos. A maioria dos métodos de client.media inicia uma tarefa e retorna o jobId dela, que você consulta periodicamente com client.jobs.getStatus(). Os métodos chamam os endpoints das APIs REST de Envio de arquivos e de Voz e mídia.

Métodos

MétodoO que faz
uploads.upload(file)Envia um arquivo e obtém a URL pública dele
uploads.uploadLarge(file, options?)Envia um arquivo de qualquer tamanho, com um vídeo ou um áudio longo indo direto para o armazenamento
uploads.uploadJson(json)Guarda um documento JSON e obtém a URL dele
uploads.importUrl(url, options?)Copia uma imagem de um endereço da web para o seu armazenamento
library.list(params?)Lista e pesquisa as suas mídias armazenadas
gallery.browse(params?)Navega pela galeria pública
gallery.toggleFavorite(jobId)Favorita uma geração, ou remove o favorito
gallery.favorites()Lista os ids das suas tarefas favoritas
contentRights.declaration()Lê a declaração de direitos de conteúdo
contentRights.confirm(input)Confirma a declaração para um link antes de ele ser importado
contentRights.authorization()Lê a autorização permanente para importações por chaves e agentes
contentRights.authorize(input)Autoriza importações por chaves e agentes, a partir da própria sessão da pessoa
contentRights.revokeAuthorization()Revoga essa autorização
media.downloadVideo(input)Baixa o vídeo por trás de um link para o seu armazenamento
media.downloadVideoProgress(downloadId, opts?)Acompanha o progresso de um download
media.videoMetadata(input)Lê a duração e o tamanho de um vídeo de rede social sem baixá-lo
media.saveToStorage(input)Copia a URL de uma mídia para o seu armazenamento
media.process(input)Corta ou recorta um arquivo armazenado, sem custo
media.discard(input)Descarta um arquivo que você acabou de criar e de que não precisa mais
media.trimVideo(input)Corta um vídeo, mantendo um intervalo
media.trimAudio(input)Corta um áudio ou o extrai de um vídeo
media.splitMedia(input)Corta um arquivo de vídeo ou de áudio em partes entre uma duração mínima e uma máxima, ou um vídeo em uma parte por tomada
media.shotCuts(input)Encontra onde cada plano de um vídeo começa e termina
media.addCaptions(input)Embute legendas em um vídeo
media.stillToVideo(input)Transforma uma imagem e uma faixa de áudio em um vídeo
media.slideshow(input)Transforma imagens e um áudio opcional em uma apresentação de slides
media.videoOverlay(input)Posiciona camadas de imagem ou de vídeo temporizadas sobre um vídeo
media.imageCollage(input)Combina de 2 a 30 imagens em uma única colagem
media.imageOverlay(input)Posiciona camadas de imagem, texto, QR e forma sobre uma imagem
media.splitIntoLayers(input, options?)Divide uma imagem em uma imagem base e camadas separadas
media.videoMask(input)Rastreia um objeto descrito em texto e retorna um vídeo de máscara
media.maskComposite(input)Coloca um vídeo sobre outro através de um vídeo de máscara, ou pixeliza ou desfoca a área mascarada
media.suggestOverlayPlacement(input)Pergunta a um modelo de visão onde uma camada deve ficar

client.uploads

uploads.upload(file)

Envia um arquivo (POST /v1/upload, multipart) e retorna a URL pública e os detalhes de armazenamento dele. O SDK envia o arquivo como form data e deixa o ambiente de execução definir o delimitador do multipart.

upload(file: File): Promise<UploadResult>

Propriedade

Tipo

const result = await client.uploads.upload(file)

const clip = await client.nodes.runAndWait("generate-video", {
  prompt: "The camera slowly pushes in",
  imageUrl: result.url,
})
CampoTipoDescrição
urlstringA URL pública do arquivo armazenado. Passe-a como imageUrl, videoUrl ou audioUrl.
assetIdstring | nullO ID do item armazenado, ou null para um upload anônimo.
thumbnailUrlstring | nullUma miniatura para imagens e vídeo, ou null.
categorystringimage, video ou audio.
filenamestringO nome de arquivo exibido.
mimeTypestringO tipo de mídia que o servidor definiu. Pode ser diferente do que o navegador declarou, por exemplo video/mp4 para um arquivo .mp4 enviado como application/octet-stream.
sizeBytesnumberO tamanho armazenado.
r2KeystringA chave de armazenamento do arquivo.

Lança StorageExceededError quando o seu armazenamento está cheio. Os nós Enviar imagem, Enviar vídeo e Enviar áudio usam o mesmo armazenamento.

uploads.uploadLarge(file, options?)

Envia um arquivo de qualquer tamanho e escolhe o caminho pelo tamanho dele. Retorna o mesmo UploadResult de upload.

uploadLarge(
  file: Blob & { name?: string },
  options?: {
    filename?: string
    onProgress?: (sentBytes: number, totalBytes: number) => void
    signal?: AbortSignal
    concurrency?: number
  },
): Promise<UploadResult>
  • Até 500 MB (UPLOAD_MAX_BYTES): o arquivo vai por upload, POST /v1/upload, com tudo o que o servidor faz ali, como a conversão de HEIC e as miniaturas.
  • Maior, só vídeo ou áudio: os bytes vão direto para o armazenamento, em partes, e nunca passam pelo servidor da API. Veja Enviar um arquivo grande de vídeo ou de áudio. Um arquivo assim é limitado principalmente pela duração: um arquivo com mais de 30 minutos é recusado com MediaTooLongError depois que chega, a cópia armazenada é removida e nada é contado no seu armazenamento. Um arquivo acima de 10 GiB lança um NodaroError com o status 422 e o código media_too_large antes de qualquer envio. Um arquivo muito maior do que a duração dele permite é recusado com media_bitrate_implausible. O arquivo é armazenado exatamente como foi enviado.

Propriedade

Tipo

const result = await client.uploads.uploadLarge(file, {
  onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)}%`),
})
console.log(result.url)

No caminho grande, qualquer falha ou um cancelamento aborta o envio no servidor. Uma conta pode ter 3 envios grandes abertos ao mesmo tempo e iniciar 20 por hora. Acima de qualquer um desses limites, o SDK lança RateLimitedError, com o código too_many_open_uploads ou rate_limited. Um arquivo que não cabe no seu armazenamento lança StorageExceededError. Um arquivo acima de 500 MB em uma implantação sem o caminho grande lança LargeUploadUnavailableError: status é 409 em uma implantação que verifica os bytes de todo envio, e 404 em um servidor mais antigo. Em um navegador, o caminho grande precisa que o armazenamento aceite um PUT de outra origem vindo da origem da página. O Nodaro Cloud aceita. UPLOAD_MAX_BYTES é exportado de @nodaro/sdk e de @nodaro/sdk/uploads.

uploads.uploadJson(json)

Guarda um documento JSON de até 25 MB (POST /v1/upload-json) e retorna { url }, a URL pública dele. Use-o, por exemplo, para o estado de design de um editor de imagens, que você passa para jobs.fromUpload como editStateUrl, para que a edição possa ser aberta de novo.

uploadJson(json: Record<string, unknown> | readonly unknown[]): Promise<UploadJsonResult>

A URL é difícil de adivinhar, mas é pública, então nunca guarde um segredo nela. O método não cria nenhum item na biblioteca.

uploads.importUrl(url, options?)

Copia uma imagem de um endereço da web para o seu armazenamento e a retorna (POST /v1/media/import-url, com o corpo { url, confirmationId? }). A cópia armazenada é um envio seu, servido de modo que um canvas do navegador possa ler os pixels dela, por exemplo para recortá-la. Uma imagem em outro site não permite isso.

importUrl(url: string, options?: { confirmationId?: string }): Promise<ImportUrlResult>

Propriedade

Tipo

A plataforma só guarda o arquivo se ele for decodificado como imagem: JPEG, PNG, WebP ou GIF. Uma imagem HEIC, HEIF ou AVIF é convertida para JPEG ou PNG.

try {
  const picture = await client.uploads.importUrl("https://example.org/photo.jpg")
  console.log(picture.url, picture.width, picture.height)
} catch (err) {
  if (err instanceof StorageExceededError && err.reason === "file_too_large") {
    // one picture over 20 MB, not a full storage
  }
}
CampoTipoDescrição
urlstringA URL pública da imagem armazenada.
thumbnailUrlstring | nullUma miniatura, ou null quando não foi possível criá-la.
assetIdstring | nullO ID do item armazenado, ou null quando nenhum foi gravado.
mimeTypestringO tipo de mídia final. Uma fonte HEIC, HEIF ou AVIF é armazenada como JPEG ou PNG.
sizeBytesnumberO tamanho armazenado.
filenamestringA última parte do caminho do endereço, ou imported-<id>.<ext>.
widthnumberA largura em pixels, ou 0 quando não foi possível lê-la.
heightnumberA altura em pixels, ou 0 quando não foi possível lê-la.
StatusErroQuando
400NodaroError com o código validation_errorO endereço não é http nem https, ou é um endereço IP privado ou reservado. O arquivo não é uma imagem decodificável, ou o formato dele não é aceito, como SVG ou TIFF.
422NodaroError com o código fetch_failedNão foi possível acessar o endereço, ou ele respondeu com um erro. Isso inclui um host que resolve para um endereço privado.
403ImportRefusedError, um ForbiddenErrorA importação de links está bloqueada na sua conta, ou ela está encerrada, pela política de infratores reincidentes da implantação (imports_blocked), a implantação não permite o site (import_source_disabled), a implantação desligou as importações de links (link_imports_disabled: envie o arquivo em vez disso), ou a confirmação de direitos de conteúdo está ausente quando é exigida, é de outro link ou de outra conta, está desatualizada, expirou ou já foi usada (um código rights_confirmation_*).
413StorageExceededError com reason igual a file_too_largeA imagem passa de 20 MB.
413StorageExceededError com reason igual a storage_limit_exceededO seu armazenamento está cheio. details traz usedBytes, quotaBytes, remainingBytes e tier.

O nó Enviar imagem usa a mesma importação quando você cola um link de imagem. Para descartar uma imagem importada de que você não precisa mais, chame media.discard().

client.library

library.list(params?)

Lista as suas mídias armazenadas com um cursor (GET /v1/library). Por padrão, retorna os itens salvos na sua biblioteca mais os itens compartilhados com você, como o seletor de mídia do editor os mostra.

list(params?: ListLibraryParams): Promise<{ data: LibraryAsset[]; nextCursor: string | null; totalCount?: number }>

Propriedade

Tipo

const { data: videos, nextCursor } = await client.library.list({ type: "video", limit: 20 })
for (const asset of videos) console.log(asset.filename, asset.url)
const { data, nextCursor } = await client.library.list({ type: "image", q: "poster" })

Uma linha da biblioteca cujo arquivo guardado não existe mais não é listada nem contada em totalCount, então o url de toda linha é uma string. Cada LibraryAsset tem id, type, filename, mimeType, sizeBytes, url, thumbnailUrl, metadata, isLibraryItem, uploadSource, source, sourceDetail, jobId, title e createdAt. jobId é a tarefa que criou o arquivo, ou null para um upload. title é o nome que o dono deu a essa tarefa com client.jobs.rename(), ou null quando ela não tem nome ou não há tarefa. Não é o filename do arquivo, que continua sendo o nome do download. Servidores mais antigos omitem os dois campos. totalCount só aparece na primeira página.

client.gallery

A galeria pública de gerações concluídas, e os seus favoritos. Um favorito é um marcador em uma geração: uma das suas, ou uma pública de qualquer pessoa. As suas tarefas o trazem como Job.favorited, e client.jobs.list({ favorited: true }) as lista. Uma implantação que oculta a galeria responde 404 nessas rotas.

gallery.browse(params?)

Lê uma página da galeria pública, das mais novas para as mais antigas (GET /v1/gallery). Não é preciso token.

browse(params?: BrowseGalleryParams): Promise<GalleryPage>

Propriedade

Tipo

const { data: items, nextCursor } = await client.gallery.browse({ type: "image", limit: 20 })

A página é { data: GalleryItem[], nextCursor, totalCount? }, com totalCount só na primeira página. Cada item é { id, type, jobName, outputUrl, thumbnailUrl, createdAt, prompt, model, title?, preview? }, em que id é o id da tarefa. title é o nome que o dono deu à tarefa, com client.jobs.rename(), ou null até ela receber um. Ele é público, ao lado do prompt. favoritesOnly só funciona com o seu próprio userId, de client.me(). Sem token, lança UnauthorizedError. Com o userId de outra pessoa, ou sem nenhum, lança ForbiddenError.

Uma implantação que não permite trabalhos públicos responde a toda visualização com uma página vazia, exceto a sua: o seu próprio userId com o seu token continua listando o seu trabalho.

gallery.toggleFavorite(jobId)

Favorita a tarefa, ou remove o favorito quando a tarefa já é favorita (POST /v1/gallery/favorite). favorited é o estado da tarefa depois da chamada.

toggleFavorite(jobId: string): Promise<{ favorited: boolean }>
const { favorited } = await client.gallery.toggleFavorite(jobId)

Você pode favoritar as suas próprias tarefas e as públicas. A tarefa privada de outra pessoa lança NotFoundError. Apps OAuth precisam do escopo assets:write.

gallery.favorites()

Retorna os ids das suas tarefas favoritas, das mais novas para as mais antigas (GET /v1/gallery/favorites). Apps OAuth precisam do escopo assets:read ou jobs:read.

favorites(): Promise<string[]>
const ids = await client.gallery.favorites()

client.contentRights

client.contentRights lê a declaração que uma pessoa confirma antes de um link ser importado, e registra a confirmação que a importação leva depois (/v1/content-rights). Veja Direitos de conteúdo para as regras.

contentRights.declaration()

declaration(): Promise<{ version: number; text: string }>

Retorna a declaração atual (GET /v1/content-rights/declaration). Mostre text como está, com uma caixa de seleção que começa desmarcada. Uma confirmação indica a version. A chamada não precisa de credencial.

contentRights.confirm(input)

confirm(input: { url: string; declarationVersion: number }): Promise<{
  id: string
  declarationVersion: number
  expiresAt: string
}>

Registra que a conta conectada confirmou a declaração para um link (POST /v1/content-rights/confirm). Qualquer link http(s) que uma importação aceita pode ser confirmado: a página de um vídeo, um arquivo, uma imagem ou uma página que o serviço de dublagem lê. Passe o id da resposta como confirmationId para media.downloadVideo(), uploads.importUrl() ou a importação que busca o link, como voices.dub() e audio.transcribe(). Uma confirmação libera um download desse link, pela mesma conta, sob a declaração atual, dentro de uma hora. Um 409 rights_confirmation_stale significa que a declaração mudou depois que você a leu: leia de novo e peça de novo.

const { version, text } = await client.contentRights.declaration()
// Show `text` with a checkbox. Once it is ticked:
const { id } = await client.contentRights.confirm({ url, declarationVersion: version })
const { downloadId } = await client.media.downloadVideo({ url, maxHeight: 1080, confirmationId: id })

Se um download sem confirmação é recusado é uma configuração da implantação. Quando ela está ativada, esse download é recusado com 403 rights_confirmation_required. Envie sempre uma confirmação.

contentRights.authorization()

authorization(): Promise<{ id: string; declarationVersion: number; createdAt: string } | null>

Retorna a autorização permanente da conta para importações pelas suas chaves de API, apps conectados e agentes de IA (GET /v1/content-rights/authorization). Retorna null quando não há nenhuma: nunca foi dada, foi revogada ou foi dada para uma declaração anterior.

contentRights.authorize(input)

authorize(input: { declarationVersion: number }): Promise<{
  id: string
  declarationVersion: number
  createdAt: string
}>

Registra que a pessoa autorizou importações pelas suas chaves, apps e agentes, para a versão da declaração que ela viu (POST /v1/content-rights/authorization). Chame-o a partir da própria sessão conectada da pessoa. Uma chave, um app ou um agente recebe 403 forbidden. Um 409 rights_confirmation_stale significa que a declaração mudou: leia de novo e peça de novo.

contentRights.revokeAuthorization()

revokeAuthorization(): Promise<{ revoked: boolean }>

Revoga a autorização permanente (DELETE /v1/content-rights/authorization). O registro é mantido. revoked é false quando não havia nada para revogar. Chame-o a partir da própria sessão da pessoa.

client.media: importar e preparar

media.downloadVideo(input)

Baixa o vídeo por trás de um link, seja a página do vídeo ou um link direto para um arquivo de vídeo, para o seu armazenamento (POST /v1/download-video). Retorna um downloadId, não um ID de tarefa. Acompanhe-o com downloadVideoProgress(). O arquivo final vai para a sua biblioteca.

downloadVideo(input: {
  url: string
  maxHeight?: number
  sectionStartSec?: number
  sectionEndSec?: number
  exactSection?: boolean
  requireAudio?: boolean
  confirmationId?: string
}): Promise<{ downloadId: string }>

Propriedade

Tipo

const { downloadId } = await client.media.downloadVideo({
  url: "https://youtu.be/dQw4w9WgXcQ",
  maxHeight: 720,
})

media.downloadVideoProgress(downloadId, opts?)

Transmite ao vivo o progresso de um download como um iterador assíncrono (GET /v1/download-video/progress/:id, server-sent events). Emite um evento a cada 500 ms, aproximadamente, até o download terminar ou falhar, e então se encerra.

downloadVideoProgress(downloadId: string, opts?: { signal?: AbortSignal }): AsyncGenerator<DownloadVideoProgress>

Propriedade

Tipo

for await (const event of client.media.downloadVideoProgress(downloadId)) {
  console.log(`${event.phase} ${event.percent}%`)
  if (event.phase === "completed") console.log("Stored at", event.videoUrl)
  if (event.phase === "failed") console.error(event.error)
}

Cada evento é { phase, percent, videoUrl?, thumbnailUrl?, error? }. Comece a iterar logo depois que downloadVideo() retornar, porque o registro de progresso expira pouco depois do fim do download. O timeoutMs do cliente não se aplica, porque downloads grandes levam minutos.

media.videoMetadata(input)

Lê a duração, as dimensões, o título e o status de transmissão ao vivo de um vídeo de rede social sem baixá-lo (POST /v1/video-metadata). Responde diretamente, sem tarefa. Use-o para decidir se vale buscar apenas um trecho.

videoMetadata(input: { url: string }): Promise<VideoMetadata>

Propriedade

Tipo

const meta = await client.media.videoMetadata({ url: "https://youtu.be/dQw4w9WgXcQ" })

Os campos são preenchidos na medida do possível: uma plataforma pode não informar todos.

media.saveToStorage(input)

Copia um arquivo de mídia de uma URL para o seu armazenamento no Nodaro (POST /v1/save-to-storage). O servidor busca o arquivo, então nada passa pelo seu cliente.

saveToStorage(input: { mediaUrl: string; filename?: string; mediaType?: "image" | "video" | "audio" }): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.saveToStorage({ mediaUrl: "https://example.com/intro.mp4", mediaType: "video" })

O nó Salvar no armazenamento faz o mesmo dentro de um workflow.

media.process(input)

Corta ou recorta um arquivo que já está no seu armazenamento (POST /v1/media/process). Responde diretamente e não custa nada. Use-o para preparar uma fonte antes de uma etapa paga.

process(input: {
  sourceUrl: string
  type: "video" | "audio"
  trim?: { startTime: number; endTime: number }
  crop?: { x: number; y: number; width: number; height: number }
  format?: "mp4" | "webm" | "mp3" | "wav" | "m4a" | "aac"
  deleteSource?: boolean
}, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<{ data: MediaProcessResult }>

Propriedade

Tipo

const { data } = await client.media.process({
  sourceUrl: stored.url,
  type: "video",
  trim: { startTime: 12, endTime: 42 },
})
console.log(data.url, data.sizeBytes)

O resultado tem url, thumbnailUrl, assetId, sizeBytes, mimeType e metadata.

media.discard(input)

Descarta um arquivo que você acabou de criar e de que não precisa mais (POST /v1/media/discard). Exemplos são um download de link que você substituiu antes de usar, um corte substituído por um mais novo e uma imagem que você importou e depois cancelou.

discard(input: { url: string }): Promise<{ data: { discarded: boolean } }>

Propriedade

Tipo

discard() não é uma exclusão geral. O arquivo só é removido quando todas estas condições são verdadeiras:

  • O arquivo é seu.
  • O arquivo foi criado por downloadVideo(), process() ou uma importação de URL, como uploads.importUrl().
  • O arquivo tem menos de 24 horas.
  • Nenhuma tarefa sua usa o arquivo, como saída ou como entrada, por exemplo o videoUrl de uma execução.

A resposta é então { data: { discarded: true } }. Caso contrário, nada é alterado, e a chamada falha com um erro 409 cujo código é not_discardable. discarded: false quer dizer que não havia nada seu nesse endereço: o arquivo já não existe, ou não é seu.

await client.media.discard({ url: oldCut.url })

media.trimVideo(input)

Corta um vídeo, mantendo um intervalo (POST /v1/trim-video), como faz o nó Cortar vídeo. Informe o intervalo na unidade que for mais conveniente.

trimVideo(input: {
  videoUrl: string
  startTime?: number
  endTime?: number
  trimStartFrames?: number
  trimEndFrames?: number
  trimStartSeconds?: number
  trimEndSeconds?: number
  keepFirstSeconds?: number
  keepLastSeconds?: number
}): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.trimVideo({ videoUrl, keepFirstSeconds: 15 })

media.trimAudio(input)

Corta um áudio, mantendo um intervalo, ou o extrai de um vídeo (POST /v1/trim-audio), como faz o nó Cortar áudio.

trimAudio(input: {
  videoUrl?: string
  audioUrl?: string
  audioFormat?: "mp3" | "wav" | "aac"
  startTime?: number
  endTime?: number
}): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.trimAudio({ videoUrl, startTime: 5, endTime: 35 })

media.splitMedia(input)

Corta um vídeo, um arquivo de áudio ou ambos em partes consecutivas (POST /v1/split-media), como faz o nó Dividir em partes. Cada entrada é dividida separadamente.

splitMedia(input:
  | {
      videoUrl?: string
      audioUrl?: string
      mode?: "duration"
      chunkDuration: number
      minPartDuration?: number
      audioFormat?: "mp3" | "wav" | "aac"
    }
  | { videoUrl: string; mode: "shots" }
): Promise<{ jobId: string }>

Propriedade

Tipo

Uma execução custa 22 créditos, seja qual for o número de partes. A saída da tarefa concluída tem videoUrls e audioUrls, as partes em ordem, chunkCount e partDurationsSec, a duração exata de cada parte. Quando as duas entradas foram divididas, audioPartDurationsSec lista as durações das partes de áudio. Um arquivo pode ter até 3 horas e gerar no máximo 200 partes.

const { jobId } = await client.media.splitMedia({ videoUrl, chunkDuration: 60, minPartDuration: 30 })

Com mode: "shots", um vídeo é cortado em uma parte por tomada, nos cortes medidos a partir do arquivo. Esse modo não recebe duração de parte e aceita só um vídeo: um audioUrl separado é um 400. Cada parte mantém o som do próprio vídeo. Os vídeos podem ter até 30 minutos, com no máximo 200 tomadas, e o preço é o mesmo. A saída então inclui também shotCount e shots, cada um { index, startSec, endSec, durationSec }.

const { jobId } = await client.media.splitMedia({ videoUrl: "https://example.com/ad.mp4", mode: "shots" })

media.shotCuts(input)

Encontra onde cada plano de um vídeo começa e termina (POST /v1/shot-cuts), como o nó Cortes de plano faz. Os cortes são medidos a partir do arquivo: cada quadro decodificado é avaliado, e cada corte seco começa um novo plano. Dissolvências e fades não são cortes.

shotCuts(input: { videoUrl: string; frames?: boolean }): Promise<{ jobId: string }>

Propriedade

Tipo

Uma execução tem um preço fixo, com ou sem quadros. Consulte a tarefa periodicamente. O output_data da tarefa concluída é um ShotCutsOutput:

interface ShotCutsOutput {
  json: {
    shotCount: number
    cutsSec: number[]        // where each new shot starts: ascending, never 0; [] for one shot
    durationSec: number      // the video's length
    shots: Array<{
      index: number
      startSec: number       // seconds from the first frame, to the millisecond
      endSec: number         // the next shot's start, or the video's end
      durationSec: number
      firstFrameUrl?: string // with frames: the shot's first frame (PNG)
      lastFrameUrl?: string  // with frames: its last frame
    }>
  }
  firstFrames?: string[]     // with frames: each shot's first frame, in shot order
  lastFrames?: string[]      // with frames: each shot's last frame, in shot order
}
const { jobId } = await client.media.shotCuts({ videoUrl: "https://example.com/ad.mp4", frames: true })

client.media: legendas

media.addCaptions(input)

Embute legendas em um vídeo (POST /v1/add-captions), como faz o nó Adicionar legendas. Informe as palavras como text, informe captions com tempos por palavra ou deixe o Nodaro transcrever a fala, que é o padrão.

addCaptions(input: AddCaptionsInput): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.addCaptions({
  videoUrl: "https://example.com/talk.mp4",
  style: "word-highlight",
  maxWordsPerLine: 2,
})

De onde vêm as palavras. Quando uma chamada traz várias fontes, as captions com tempos por palavra têm prioridade, depois o text no estilo subtitle e, por último, a transcrição. No subtitle, text é a legenda: ela é embutida como um único bloco estático durante o vídeo inteiro e nunca é substituída por uma transcrição. Use \n no texto para forçar uma quebra de linha. Em um estilo cinético, text é apenas um texto de reserva. Ele é usado quando a transcrição não encontra nada ou autoTranscribe é false, e então as palavras dele são distribuídas por igual ao longo do vídeo.

Estilos e looks. Nos estilos cinéticos, um look não definido é renderizado como outline. No subtitle, é renderizado como clean. Os ajustes explícitos substituem campos individuais do look. Um segmento que define o próprio look parte dessa predefinição e não herda os ajustes do nível superior.

Ajustes no subtitle. Os ajustes de estilo (look, fontFamily, fontWeight, strokeColor, strokeWidth, uppercase, positionY e maxWordsPerLine) também funcionam no subtitle. Um subtitle com qualquer um deles é cobrado pelo preço cinético, e um subtitle de texto simples é cobrado pelo preço mais baixo. highlightColor e animate são exclusivos dos estilos cinéticos e são recusados com um 400 no subtitle. Um subtitle transcrito automaticamente também é cobrado pelo preço cinético.

Linhas. word-highlight, karaoke e bouncy mostram uma linha por vez. Uma linha termina no fim de uma frase, em uma pausa de 0,5 segundo ou mais, quando ocupa cerca de 85% da largura do quadro ou ao chegar a maxWordsPerLine palavras. word-pop mostra uma palavra por vez, então maxWordsPerLine não tem efeito nesse estilo. Uma página de tiktok-words nunca atravessa o fim de uma frase nem uma pausa. Ambas ficam na tela por no máximo 1,5 segundo depois da última palavra falada. O startMs e o endMs de uma palavra marcam o tempo do efeito dela, não por quanto tempo ela fica visível.

Mecanismos de transcrição. Um estilo cinético precisa de tempos por palavra, então transcribeProvider deve ser incredibly-fast-whisper, o padrão aqui, elevenlabs-stt ou nemotron-3-5-transcribe. O Nemotron 3.5 Transcribe é uma única cobrança: a renderização mais os minutos iniciados do vídeo. Veja Adicionar legendas. whisper não tem tempos por palavra. Ele é recusado com 400 validation_error apenas quando a transcrição é a única fonte possível das palavras. No subtitle, qualquer mecanismo funciona, porque um subtitle só precisa dos tempos de cada frase.

Taxa de quadros. Uma renderização estilizada mantém a taxa de quadros do vídeo de origem, arredondada para um número inteiro entre 15 e 60. Uma fonte com taxa de quadros variável, ou um clipe longo demais para o limite de quadros, é renderizado a 30 fps.

Transcrever, corrigir e embutir

As words de uma tarefa de client.audio.transcribe() têm exatamente o formato que captions aceita. Corrija uma palavra e depois embuta as legendas sem uma segunda transcrição:

import type { TranscribeJobOutput } from "@nodaro/sdk"

const { jobId } = await client.audio.transcribe({
  audioUrl: "https://example.com/talk.mp3",
  provider: "elevenlabs-stt", // always returns word timings
})
// ...poll until the job completes, then:
const { data: job } = await client.jobs.get(jobId)
const { words = [] } = job.output_data as TranscribeJobOutput

const corrected = words.map((w, i) => (i === 7 ? { ...w, text: "Nodaro" } : w))
await client.media.addCaptions({
  videoUrl: "https://example.com/talk.mp4",
  captions: corrected,
  autoTranscribe: false,
  style: "word-highlight",
})

client.media: renderizar e compor

media.stillToVideo(input)

Transforma uma imagem fixa e uma faixa de áudio em um MP4 (POST /v1/still-to-video), como faz o nó Imagem fixa para vídeo. É renderizado no servidor, sem modelo de IA, e não custa créditos. O vídeo dura o mesmo que o áudio; não há campo de duração.

stillToVideo(input: {
  imageUrl: string
  audioUrl: string
  motion?: "none" | "zoom-in" | "zoom-out" | "pan-left" | "pan-right" | "ken-burns"
  intensity?: number
  resolution?: "720p" | "1080p" | "4K"
  aspectRatio?: "16:9" | "9:16" | "1:1" | "4:3"
  fps?: 24 | 30
  fit?: "cover" | "contain"
  padColor?: string
}): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.stillToVideo({ imageUrl: coverUrl, audioUrl: podcastUrl, motion: "ken-burns" })

media.slideshow(input)

Transforma de 2 a 100 imagens e uma faixa de áudio opcional em uma apresentação de slides em MP4 (POST /v1/slideshow), como faz o nó Apresentação de slides. Não custa créditos. Para uma única imagem, use stillToVideo().

slideshow(input: {
  imageUrls: string[]
  audioUrl?: string
  imageDurations?: Array<number | null>
  perImageDuration?: number
  transition?: string
  transitionDuration?: number
  motion?: "none" | "zoom-in" | "zoom-out" | "ken-burns" | "alternate"
  intensity?: number
  resolution?: "720p" | "1080p" | "4K"
  aspectRatio?: "16:9" | "9:16" | "1:1" | "4:3"
  fps?: 24 | 30
  fit?: "cover" | "contain"
  padColor?: string
}): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.slideshow({ imageUrls: frames, audioUrl: musicUrl, motion: "alternate" })

Com áudio, o tempo é dividido por igual, a menos que imageDurations fixe a duração de algumas imagens. Sem áudio, o vídeo dura o número de imagens vezes perImageDuration e fica sem som.

media.videoOverlay(input)

Posiciona de 1 a 20 camadas de imagem ou de vídeo temporizadas sobre um vídeo em uma única passada (POST /v1/video-overlay), como faz o nó Sobreposição em vídeo. A renderização é local, sem modelo de IA.

videoOverlay(input: VideoOverlayRequest): Promise<{ jobId: string }>

Propriedade

Tipo

Cada camada recebe imageUrl ou videoUrl, e start, em segundos, de 0 a 3.600. Um end opcional encerra a camada; sem end, ela fica até o fim do vídeo. preset é card, corner-badge ou full-frame. Os campos da caixa, x e y, vão de -100 a 100, e width e height, de 1 a 100, todos em porcentagem do quadro de saída. Sem height, a caixa segue a proporção da imagem ou do vídeo. Um campo de caixa explícito substitui a predefinição. Uma camada sem nenhum dos dois é um selo de canto, no canto inferior direito ou no corner que ela indicar. opacity vai de 0 a 1, e zIndex vai de 0 a 100. animate vem ativado por padrão em uma camada de imagem e desativado em uma camada de vídeo.

Camadas de vídeo e layouts

Uma camada de vídeo toca a partir do primeiro quadro no start dela. Ela para no end dela ou no fim do vídeo base. Se o vídeo da camada acabar antes, o último quadro dele fica na tela.

Uma camada de vídeo fica sem som, a menos que tenha sound: { volume }, com um volume de 0 a 1. O áudio dela é então mixado com o áudio base durante a janela dela, sob um limitador que mantém os picos em -1 dBFS ou abaixo. Quando nenhuma camada tem som, o áudio base é mantido como está.

layout posiciona o vídeo base e a primeira camada de vídeo:

layoutResultado
video-bottom, video-topO vídeo base inteiro, na largura total, junto à borda inferior ou superior
stack-wholeO vídeo base inteiro logo acima da primeira camada de vídeo, com o par centralizado
stack-filledO vídeo base preenche a metade de cima, e a camada de vídeo a metade de baixo, ambos recortados
pipA primeira camada de vídeo, com 30% da largura do quadro, a 4% do corner dela

Todo layout, exceto pip, exige outputAspect. As duas pilhas e pip exigem uma camada de vídeo. Uma pilha não aceita baseBox.

const { jobId } = await client.media.videoOverlay({
  videoUrl,
  layers: [
    { imageUrl: logoUrl, start: 0, preset: "corner-badge", corner: "top-right" },
    { imageUrl: offerCardUrl, start: 8, end: 14, preset: "card" },
  ],
})

Preço da sobreposição em vídeo

Uma execução só com camadas de imagem custa 22 créditos, seja qual for o número de camadas ou a duração. Uma execução com qualquer camada de vídeo é cobrada a cada 5 segundos iniciados do vídeo base. Essa execução aceita um vídeo base de até 60 segundos e no máximo 2 camadas de vídeo de até 200 MB cada. O vídeo base é medido antes de qualquer cobrança. Um vídeo base com mais de 60 segundos falha com video_overlay_too_long, e um ilegível, com invalid_media_duration. Quando todas as camadas começam depois do fim do vídeo base, a execução falha com video_overlay_starts_after_end.

A saída da tarefa concluída tem videoUrl, thumbnailUrl, width, height, durationSec e warnings. Cada aviso é { layer?, slot?, code, detail }, com um código como clipped, skipped, animated_first_frame, audio_reencoded ou layer_no_audio. layer_no_audio significa que uma camada de vídeo com sound não tinha faixa de áudio, então ela foi desenhada sem som.

media.imageCollage(input)

Combina de 2 a 30 imagens em uma única colagem grande, em 2K ou 4K (POST /v1/image-collage), como faz o nó Colagem de imagens.

imageCollage(input: {
  imageUrls: string[]
  imageSizes?: Array<0 | 1 | 2 | 3>
  numbered?: boolean
  imageLabels?: Array<string | null>
  badgePosition?: "top-left" | "top-right"
  layout?: "smart" | "grid"
  resolution?: "2K" | "4K"
  aspectRatio?: string
  gap?: number
  backgroundColor?: string
}): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.media.imageCollage({
  imageUrls: shotUrls,
  numbered: true,
  imageLabels: ["Wide", "Medium", "Close-up"],
})

Números e rótulos nunca mudam o layout, o tamanho de saída nem o preço. Um rótulo longo demais para a imagem é encurtado com reticências.

media.imageOverlay(input)

Posiciona de 1 a 12 camadas sobre uma imagem base, com precisão de pixel (POST /v1/image-overlay), como faz o nó Sobreposição em imagem. É uma composição sem modelo de IA. Custa 11 créditos, e cada tamanho de plataforma extra em variants aumenta o preço.

imageOverlay(input: {
  imageUrl: string
  layers: Array<{
    kind?: "image" | "text" | "qr" | "shape"
    imageUrl?: string
    anchor?: "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right"
    x?: number
    y?: number
    width?: number
    height?: number
    opacity?: number
    rotation?: number
    blend?: "over" | "multiply" | "screen"
    fit?: "contain" | "cover" | "stretch"
    shadow?: { blur: number; offsetX: number; offsetY: number; color: string; opacity: number }
    roundedCorners?: number
    zIndex?: number
    text?: OverlayTextStyle
    qr?: OverlayQrStyle
    shape?: OverlayShapeStyle
    effects?: OverlayImageEffects
  }>
  canvas?: { width: number; height: number; backgroundColor?: string }
  baseFit?: "contain" | "cover"
  outputFormat?: "png" | "jpg" | "webp"
  variants?: string[]
  maskMode?: "none" | "layers" | "around" | "outside"
  maskSpread?: number
  qrText?: string
}): Promise<{ jobId: string }>

Propriedade

Tipo

Camadas. Uma camada é de um destes quatro tipos:

  • Uma imagem: kind: "image", o padrão, com imageUrl.
  • Texto real: kind: "text" com um objeto text. Ele define o conteúdo, a fonte, o peso, a cor, o alinhamento, o contorno e a caixa de fundo, além de um tamanho em porcentagem da altura da base.
  • Um QR code: kind: "qr" com qr: { text }.
  • Uma forma chapada: kind: "shape" com shape: { shape, color }.

As posições são porcentagens da imagem base, então a mesma chamada funciona em uma prévia em 1K e em uma renderização em 4K:

  • anchor é uma de nove posições, center por padrão.
  • x e y deslocam a camada a partir da âncora, em porcentagem da largura e da altura da base. Com uma âncora à direita ou embaixo, um valor negativo a desloca para dentro.
  • width é em porcentagem da largura da base, 25 por padrão. A altura segue a proporção da camada, a menos que você defina height, e então fit decide como a camada preenche a caixa.
  • opacity vai de 0 a 1, rotation é em graus em torno do centro da camada, e blend é over (o padrão), multiply ou screen.
  • shadow adiciona uma sombra suave, roundedCorners arredonda os cantos, em pixels, e zIndex define a ordem de empilhamento.
const { jobId } = await client.media.imageOverlay({
  imageUrl: productShotUrl,
  layers: [{ imageUrl: logoUrl, anchor: "bottom-right", x: -4, y: -6, width: 12, opacity: 0.95 }],
  variants: ["youtube-thumbnail"],
})

A saída da tarefa concluída tem imageUrl, com width e height, maskUrl e variants, cada uma no formato { id, label, width, height, url }. As camadas SVG são desenhadas com nitidez no tamanho final. Uma camada QR com qr.fromInput: true obtém o conteúdo de qrText, e uma execução sem qrText é recusada com um 400 que o indica.

media.splitIntoLayers(input, options?)

Divide uma imagem em uma imagem base e camadas separadas (POST /v1/split-into-layers), cada elemento no próprio PNG transparente, com nome, descrição, ordem de empilhamento e a caixa em que fica na base.

splitIntoLayers(
  input: {
    imageUrl: string
    maxLayers?: number                       // 1–99, default 9
    size?: "1K" | "1.5K" | "2K" | "auto"     // default "1K"
    prompt?: string                          // what to separate, up to 2,000 characters
    sessionId?: string                       // one of your sessions: the job is filed in it
    origin?: string                          // your app's slug, stored on the job
  },
  options?: {
    idempotencyKey?: string                  // sent as the Idempotency-Key header (8+ characters)
    signal?: AbortSignal
    timeoutMs?: number
  },
): Promise<{ jobId: string; deduped?: true }>
  • maxLayers limita as camadas. Uma imagem com mais elementos tem os elementos juntados em menos camadas, e nenhum é descartado.
  • size é a quantidade de pixels de cada imagem: 1K é cerca de um megapixel, e auto mantém o tamanho da própria imagem, entre 1K e 2K.
  • prompt diz quais elementos separar. Ele pode trazer marcas <bbox>x1 y1 x2 y2</bbox>, de 0 a 1000, para indicar uma área. Em branco, os elementos principais são encontrados automaticamente.
  • Um corpo malformado é um 400 validation_error antes de qualquer crédito ser reservado. Uma sessão que não é sua é um 404, antes de qualquer coisa ser criada ou cobrada.
  • Com options.idempotencyKey, uma nova tentativa da mesma solicitação responde a tarefa que ela já iniciou (deduped: true), em vez de iniciar e cobrar uma segunda.

No Nodaro Cloud, uma execução reserva o preço do máximo de imagens que pode retornar, maxLayers + 1 com a base, no tamanho dela. Ela é cobrada só pelas imagens que de fato retornar. 1K e 1.5K têm o mesmo preço, e 2K e auto também. Uma execução que não encontra nenhum elemento termina só com a imagem base, pelo preço de uma imagem. client.nodes.quote("split-into-layers", input) informa a reserva de uma execução antes de ela começar, sem iniciar nada.

Consulte jobs.get(jobId) periodicamente. O output_data da tarefa concluída é um SplitIntoLayersOutput:

interface SplitIntoLayersOutput {
  imageUrl: string        // the base picture: an opaque PNG
  layers: string[]        // each layer's transparent PNG, bottom to top
  layerData: Array<{      // one per layer, in the same order
    name?: string
    description?: string
    zIndex: number        // stacking order: 1 sits on the base, higher is drawn above
    width?: number        // the layer FILE's own pixels, not the base's
    height?: number
    box?: { x1: number; y1: number; x2: number; y2: number }           // where it sits on the base, in the base's pixels
    boxNormalized?: { x1: number; y1: number; x2: number; y2: number } // the same box on a 0–1000 scale of the base
    url: string
    baseUrl?: string      // the base picture this layer was cut from: the same as imageUrl
  }>
  layerCount: number      // layers saved
  layersNotSaved?: number // layers that could not be saved; they are not charged
  libraryImages?: Array<{ url: string; name?: string }> // each layer as filed in the Library, under its name
}

Uma camada não está em pixels da base: ela é recortada no próprio elemento, com mais ou menos a quantidade de pixels da configuração de tamanho. Para colocar uma camada de volta no lugar, redimensione-a para a box dela, em que x1 e y1 são o canto superior esquerdo e x2 e y2 o inferior direito.

const { jobId } = await client.media.splitIntoLayers({ imageUrl: "https://example.com/poster.png", maxLayers: 5 })

Referência completa: Dividir em camadas.

media.videoMask(input)

Rastreia ao longo de um vídeo um objeto descrito em texto simples e retorna um vídeo de máscara em preto e branco, branco onde o objeto está (POST /v1/video-mask), como faz o nó Máscara de vídeo.

videoMask(input: {
  videoUrl: string
  prompt: string
  threshold?: number
  provider?: "sam-3.1" | "sam-3"
  holdLastMask?: boolean
  minSubjectHeightPct?: number
  maxSubjectHeightPct?: number
  zone?: { leftPct?: number; rightPct?: number; topPct?: number; bottomPct?: number } | null
  perShot?: boolean
  redetectEverySec?: number
}): Promise<{ jobId: string }>

Propriedade

Tipo

O preço depende da duração do clipe, de 55 a 3.108 créditos com SAM 3.1. Um clipe acima de 30 fps conta como proporcionalmente mais longo. A saída da tarefa concluída tem videoUrl (a máscara), width, height, frames, chunks, shots, coverage, kept e recipe. chunks conta as requisições enviadas ao modelo. shots vale 1, a menos que perShot tenha encontrado cortes. recipe é a versão do método de mascaramento, que muda sempre que o mesmo clipe com as mesmas configurações daria uma máscara diferente. kept só é false quando os filtros de tamanho e de zona não deixaram nada em nenhum quadro. Leia kept em vez de coverage, que é arredondado para 4 casas decimais.

media.maskComposite(input)

Coloca um vídeo de primeiro plano sobre um vídeo de fundo através de um vídeo de máscara (POST /v1/mask-composite), como faz o nó Composição por máscara. O branco na máscara mostra o primeiro plano. Com fill: "pixelate" ou "blur", a área mascarada mostra o próprio fundo, pixelizado ou desfocado, e nenhum primeiro plano é necessário.

maskComposite(input: {
  foregroundUrl?: string
  backgroundUrl: string
  maskUrl: string
  invertMask?: boolean
  feather?: number
  grow?: number
  opacity?: number
  fill?: "video" | "pixelate" | "blur"
  pixelSizePct?: number
  blurStrengthPct?: number
  backgroundFit?: "cover" | "contain" | "stretch"
  audioSource?: "foreground" | "background" | "mix" | "none"
}): Promise<{ jobId: string }>

Propriedade

Tipo

Uma execução custa 11 créditos a cada 5 segundos iniciados do resultado.

const { jobId: maskJobId } = await client.media.videoMask({ videoUrl: talkUrl, prompt: "the person" })
// Poll the mask job. Its output videoUrl is the mask.
const { jobId } = await client.media.maskComposite({ foregroundUrl: talkUrl, backgroundUrl: beachUrl, maskUrl })

media.suggestOverlayPlacement(input)

Pergunta a um modelo de visão onde uma camada deve ficar sobre uma imagem base (POST /v1/image-overlay/suggest-placement). O modelo mantém a camada longe de rostos, do assunto principal e de texturas carregadas. Responde diretamente, sem uma tarefa a consultar periodicamente, e é cobrado como uma chamada do nó Descrever imagem. Nada é composto: você aplica o posicionamento.

suggestOverlayPlacement(input: {
  imageUrl: string
  layerAspect?: number
  intent?: string
  safeArea?: { x: number; y: number; w: number; h: number }
  llmModel?: string
}): Promise<{ jobId: string; placement: OverlayPlacement }>

Propriedade

Tipo

const { placement } = await client.media.suggestOverlayPlacement({
  imageUrl: baseUrl,
  intent: "a logo",
  layerAspect: 2.5,
})
const { reason, ...box } = placement // anchor, x, y and width, in imageOverlay's units
await client.media.imageOverlay({ imageUrl: baseUrl, layers: [{ imageUrl: logoUrl, ...box }] })

placement tem anchor, x, y e width nas unidades em porcentagem de imageOverlay, além de um reason de uma frase que você pode mostrar ao usuário. jobId é o registro de cobrança.

Perguntas frequentes

Como enviar um arquivo com o SDK do Nodaro?

Chame client.uploads.upload(file) com um File. Ele retorna uma url pública que você pode passar para qualquer nó que receba a URL de uma imagem, de um vídeo ou de um áudio.

Como adicionar legendas a um vídeo pelo código?

Chame client.media.addCaptions com a videoUrl e um style. Sem text nem captions, o Nodaro transcreve a fala. A chamada retorna um jobId; a tarefa concluída contém o vídeo legendado.

Quais métodos de mídia não custam créditos?

stillToVideo e slideshow são renderizados sem modelo de IA e não custam créditos, e media.process é gratuito. um videoOverlay só com imagens custa 22 créditos por execução, um com uma camada de vídeo é cobrado a cada 5 segundos iniciados do vídeo base, e imageOverlay custa 11 créditos, e cada tamanho de plataforma extra aumenta o preço.

Como favoritar uma geração pelo código?

Chame client.gallery.toggleFavorite(jobId). Ele favorita a tarefa, ou remove o favorito quando a tarefa já é favorita. Liste os seus favoritos com client.gallery.favorites() ou client.jobs.list({ favorited: true }).

Como acompanhar o download de um vídeo?

client.media.downloadVideo retorna um downloadId. Percorra client.media.downloadVideoProgress(downloadId) para receber a fase e a porcentagem até o download terminar ou falhar.

Última atualização

Nesta página