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étodo | O 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,
})| Campo | Tipo | Descrição |
|---|---|---|
url | string | A URL pública do arquivo armazenado. Passe-a como imageUrl, videoUrl ou audioUrl. |
assetId | string | null | O ID do item armazenado, ou null para um upload anônimo. |
thumbnailUrl | string | null | Uma miniatura para imagens e vídeo, ou null. |
category | string | image, video ou audio. |
filename | string | O nome de arquivo exibido. |
mimeType | string | O 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. |
sizeBytes | number | O tamanho armazenado. |
r2Key | string | A 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 porupload,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
MediaTooLongErrordepois que chega, a cópia armazenada é removida e nada é contado no seu armazenamento. Um arquivo acima de 10 GiB lança umNodaroErrorcom o status 422 e o códigomedia_too_largeantes de qualquer envio. Um arquivo muito maior do que a duração dele permite é recusado commedia_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
}
}| Campo | Tipo | Descrição |
|---|---|---|
url | string | A URL pública da imagem armazenada. |
thumbnailUrl | string | null | Uma miniatura, ou null quando não foi possível criá-la. |
assetId | string | null | O ID do item armazenado, ou null quando nenhum foi gravado. |
mimeType | string | O tipo de mídia final. Uma fonte HEIC, HEIF ou AVIF é armazenada como JPEG ou PNG. |
sizeBytes | number | O tamanho armazenado. |
filename | string | A última parte do caminho do endereço, ou imported-<id>.<ext>. |
width | number | A largura em pixels, ou 0 quando não foi possível lê-la. |
height | number | A altura em pixels, ou 0 quando não foi possível lê-la. |
| Status | Erro | Quando |
|---|---|---|
| 400 | NodaroError com o código validation_error | O 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. |
| 422 | NodaroError com o código fetch_failed | Nã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. |
| 403 | ImportRefusedError, um ForbiddenError | A 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_*). |
| 413 | StorageExceededError com reason igual a file_too_large | A imagem passa de 20 MB. |
| 413 | StorageExceededError com reason igual a storage_limit_exceeded | O 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, comouploads.importUrl(). - O arquivo tem menos de 24 horas.
- Nenhuma tarefa sua usa o arquivo, como saída ou como entrada, por exemplo o
videoUrlde 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:
layout | Resultado |
|---|---|
video-bottom, video-top | O vídeo base inteiro, na largura total, junto à borda inferior ou superior |
stack-whole | O vídeo base inteiro logo acima da primeira camada de vídeo, com o par centralizado |
stack-filled | O vídeo base preenche a metade de cima, e a camada de vídeo a metade de baixo, ambos recortados |
pip | A 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, comimageUrl. - Texto real:
kind: "text"com um objetotext. 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"comqr: { text }. - Uma forma chapada:
kind: "shape"comshape: { 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,centerpor padrão.xeydeslocam 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ê definaheight, e entãofitdecide como a camada preenche a caixa.opacityvai de 0 a 1,rotationé em graus em torno do centro da camada, eblendéover(o padrão),multiplyouscreen.shadowadiciona uma sombra suave,roundedCornersarredonda os cantos, em pixels, ezIndexdefine 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 }>maxLayerslimita 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, eautomantém o tamanho da própria imagem, entre 1K e 2K.promptdiz 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_errorantes de qualquer crédito ser reservado. Uma sessão que não é sua é um404, 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.
Páginas relacionadas
Vozes e áudio
Tarefas e execuções
Envio de arquivos
Voz e mídia
Adicionar legendas
Última atualização
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.
Vozes e áudio
Navegue pelas vozes, troque e substitua vozes, crie novas vozes, duble vídeos e separe, mixe e transcreva áudio em TypeScript com o SDK do Nodaro.