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

Envio de arquivos

Envie imagens, vídeo e áudio com POST /v1/upload, copie de URLs, importe vídeos de links, corte mídia salva, busque na biblioteca e crie links para arquivos.

O envio de arquivos coloca as suas próprias imagens, vídeos e áudios no armazenamento do Nodaro, para que qualquer nó possa usá-los pela URL. POST /v1/upload armazena um arquivo e retorna a URL dele. Outras rotas copiam um arquivo de uma URL, importam um vídeo de uma rede social, cortam um arquivo armazenado de graça ou listam a mídia que você armazenou.

Endpoints

MétodoCaminhoO que faz
POST/v1/uploadEnvia um arquivo, como multipart form data.
POST/v1/uploads/large/startInicia um envio grande de vídeo ou de áudio que vai direto para o armazenamento.
POST/v1/uploads/large/completeConclui um envio grande e retorna o arquivo armazenado.
POST/v1/uploads/large/abortDesiste de um envio grande.
POST/v1/upload-jsonGuarda um documento JSON, de até 25 MB, e retorna a URL pública dele. Por exemplo, o estado de design de um editor de imagens para uma imagem editada. A URL é difícil de adivinhar, mas é pública, então nunca guarde um segredo nela.
POST/v1/save-to-storageCopia um arquivo de uma URL para o seu armazenamento, como uma tarefa.
POST/v1/download-videoImporta um vídeo de uma rede social ou de um link direto de vídeo.
GET/v1/download-video/progress/:downloadIdO progresso da importação, como server-sent events.
POST/v1/video-metadataLê a duração, o tamanho e o título de um vídeo sem baixá-lo.
POST/v1/media/processCorta ou recorta um arquivo de vídeo ou de áudio armazenado. Grátis e síncrono.
POST/v1/media/import-urlCopia uma imagem de um endereço da web para o seu armazenamento.
POST/v1/media/discardDescarta um arquivo que você acabou de criar e de que não precisa mais.
GET/v1/libraryA sua biblioteca de mídia, do mais novo para o mais antigo, com busca e filtros.
POST/v1/library/save-generatedSalva um dos seus arquivos na sua biblioteca.

Enviar um arquivo

Envie o arquivo como multipart form data, no campo file. Você também pode enviar type, com o valor image, video ou audio.

curl -s -X POST https://app.nodaro.ai/v1/upload \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -F "file=@portrait.png;type=image/png" \
  -F "type=image"
{
  "data": {
    "url": "https://…/portrait.png",
    "assetId": "5d6e7f80-91a2-4b3c-8d4e-5f60718293a4",
    "thumbnailUrl": "https://…/portrait-thumb.webp",
    "category": "image",
    "filename": "portrait.png",
    "mimeType": "image/png",
    "sizeBytes": 1482233,
    "r2Key": "…/portrait.png"
  }
}
// In a browser, file comes from an <input type="file">.
// In Node 20 or newer, build it from bytes:
import { readFile } from 'node:fs/promises'

const file = new File([await readFile('portrait.png')], 'portrait.png', { type: 'image/png' })
const upload = await client.uploads.upload(file)
console.log(upload.url) // pass it as imageUrl, videoUrl or audioUrl
CampoSignificado
urlA URL pública do arquivo armazenado. Use-a em qualquer nó.
assetIdO ID do arquivo no seu armazenamento.
thumbnailUrlUma miniatura para imagens e vídeo, ou null para áudio.
categoryimage, video ou audio, conforme o servidor classificou o arquivo.
filenameO nome de exibição do arquivo.
mimeTypeO tipo de arquivo que o servidor definiu. Veja abaixo.
sizeBytesO tamanho armazenado, em bytes.
r2KeyA chave do arquivo no armazenamento.

A CLI não tem comando de upload. Para copiar pelo terminal um arquivo que já está on-line para o seu armazenamento, use nodaro media save <url>.

Formatos e tipos de arquivo

MídiaFormatos
ImagemPNG, JPEG, WebP, GIF, AVIF, HEIC, HEIF. Até 25 MB.
VídeoMP4, MOV, WebM, AVI. Até 500 MB. Um vídeo ou áudio mais longo vai pelo envio grande, com até 30 minutos.
ÁudioMP3, WAV, M4A e AAC, OGG, WebM, FLAC. Até 50 MB.

Cada tipo de mídia tem um limite de tamanho próprio. O tipo que o seu cliente declara não precisa ser o padrão, porque o servidor descobre o tipo real antes de verificar o arquivo:

  • Os parâmetros são removidos. audio/webm;codecs=opus vira audio/webm.
  • As grafias alternativas comuns são convertidas. audio/vnd.dlna.adts, que o Windows usa para um arquivo .aac comum, vira audio/aac, image/jpg vira image/jpeg, e video/mov vira video/quicktime.
  • Um tipo pouco informativo é deduzido do nome do arquivo. Com application/octet-stream, ou sem tipo nenhum, a extensão decide: clip.mp4 é armazenado como video/mp4.

Um tipo que ainda assim não corresponde a nenhum formato aceito retorna 400 validation_error, com a lista de formatos aceitos. O tipo que o servidor definiu volta como mimeType, e o arquivo é servido com ele.

As imagens HEIC, HEIF e AVIF são convertidas antes de serem armazenadas. Poucos navegadores mostram esses formatos, e os modelos de imagem não os aceitam. Toda via de upload de imagem armazena um arquivo assim como JPEG, ou como PNG quando a imagem tem transparência, e mimeType informa o tipo armazenado. As vias são POST /v1/upload, POST /v1/upload/image, o upload por trás das ferramentas MCP prepare_image_upload e request_image_upload, e a importação de uma URL de imagem pelo servidor. Uma via que entregou a URL do arquivo antes do upload mantém essa URL, e só o tipo de conteúdo muda. Isso inclui arquivos AVIF de 10 bits e fotos HEIC do iPhone. Esses dois são lidos por um decodificador que não mantém a transparência, então uma área transparente neles fica opaca. Um AVIF de 8 bits mantém a transparência. Um arquivo que não pode ser decodificado de forma alguma é recusado com 400.

Os vídeos MP4 e MOV são armazenados com o índice no início. Uma gravação do OBS ou de um celular costuma guardar esse índice no fim do arquivo, então a primeira busca em um arquivo grande é lenta. Todas as vias de upload de vídeo reescrevem um arquivo assim uma vez, antes de armazená-lo, copiando os fluxos dele para um novo contêiner. Nada é recodificado: a imagem e o som continuam idênticos. Um arquivo que já tem o índice no início, ou que a reescrita não consegue verificar, é armazenado exatamente como foi enviado. Como um arquivo reescrito é empacotado de novo, o tamanho armazenado pode diferir um pouco dos bytes que você enviou. sizeBytes é sempre o tamanho do arquivo armazenado, então não o compare com o tamanho ou o checksum do seu arquivo local.

Quando um envio é recusado

StatusCódigoSignificado
400validation_errorO arquivo não está em um formato aceito, ou um arquivo de imagem ou de áudio passa do limite de tamanho dele.
413storage_limit_exceededO seu armazenamento está cheio. O SDK lança StorageExceededError, com o código em reason e o seu uso e o seu limite em details: usedBytes, quotaBytes, remainingBytes e tier.
422upload_blockedA política de envio da implantação recusou o arquivo antes de armazená-lo. Mostre a message ao seu usuário como ela é. Só em implantações com essa política.

Enviar um arquivo grande de vídeo ou de áudio

POST /v1/upload guarda o arquivo inteiro no servidor e aceita no máximo 500 MB. Um arquivo de vídeo ou de áudio mais longo vai por um segundo caminho: os bytes vão do seu cliente direto para o armazenamento, em partes, e nunca passam pelo servidor da API. Um arquivo enviado assim é limitado principalmente pela duração: no máximo 30 minutos. Ele também pode ter no máximo 10 GiB.

Iniciar o envio

Envie POST /v1/uploads/large/start com { filename, mimeType, sizeBytes }. Só vídeo e áudio são aceitos. A resposta é { token, partSize, partUrls }. A sua cota de armazenamento é verificada aqui, mas nada é contado nela ainda.

Enviar as partes

A parte i são os bytes [(i-1)·partSize, i·partSize) do arquivo, e a última parte é o resto. Envie cada parte como o corpo de um PUT simples para partUrls[i-1]. Cada URL só aceita o tamanho exato da sua parte, então corte o arquivo exatamente em partSize. Não envie cabeçalhos próprios: o seu cliente HTTP define Content-Length pelo corpo. As partes podem ir em paralelo e em qualquer ordem, e uma parte que falhou pode ser enviada de novo para a mesma URL. As URLs das partes valem por 6 horas, e o token por 7 horas. partSize é o maior entre 16 MiB e sizeBytes ÷ 9.000, arredondado para cima, então um arquivo de 10 GiB tem 640 partes.

Concluir o envio

Envie POST /v1/uploads/large/complete com { token }. O servidor junta as partes, verifica se o tamanho armazenado é igual a sizeBytes e lê a duração do arquivo. A resposta tem o mesmo data de POST /v1/upload. Só agora o arquivo é contado no seu armazenamento. Chamar o complete duas vezes é seguro: a repetição retorna o resultado da primeira chamada, ou 409 upload_completing enquanto a primeira ainda está em andamento.

Para desistir, envie POST /v1/uploads/large/abort com { token }. A resposta é { data: { aborted } }. Um envio que não é concluído nem abortado termina quando o token expira, e as partes dele são removidas um dia depois.

StatusCódigoQuando
400upload_incompleteComplete: faltam partes. Envie as partes e conclua de novo.
400size_mismatchComplete: o tamanho armazenado não é sizeBytes.
403O token pertence a outra conta.
409large_upload_unavailableA implantação verifica os bytes de todo envio com uma política de envio, então este caminho fica fechado nela. Envie um arquivo de até 500 MB com POST /v1/upload.
413storage_limit_exceededStart ou complete: o arquivo não cabe no seu armazenamento.
422media_too_largeStart: o arquivo passa de 10 GiB.
422media_too_longComplete: o arquivo tem mais de 30 minutos.
422media_unreadableComplete: a duração do arquivo não pode ser lida, então ele também não tocaria no editor.
422media_bitrate_implausibleComplete: o arquivo é muito maior do que a duração dele permite. A taxa de bits média, sem contar os primeiros 16 MiB, pode ser de no máximo 2.500 Mbit/s para vídeo e 50 Mbit/s para áudio. Esses limites ficam muito acima de gravações de câmera em 4K de alta qualidade.
429too_many_open_uploadsStart: 3 envios grandes seus ainda estão abertos. Conclua ou aborte um deles.
429rate_limitedStart: mais de 20 inícios na hora atual.
503large_upload_busyStart: o servidor não consegue contar os seus envios abertos agora. Tente de novo em instantes.

Uma recusa no complete remove o arquivo armazenado, e nada é contado no seu armazenamento. Um arquivo enviado assim é armazenado exatamente como foi enviado: ele não tem o índice reescrito nem passa pela conversão de HEIC. Use este caminho só para um arquivo que POST /v1/upload não aceita.

No SDK, client.uploads.uploadLarge(file) escolhe o caminho para você: um arquivo de até 500 MB vai por POST /v1/upload, e só um maior vai por este caminho. Veja Mídia e uploads.

Usar uma URL no lugar

A maioria das rotas recebe mídia por URL, como imageUrl, videoUrl, audioUrl e referenceImageUrls, então um arquivo que já está on-line não precisa ser enviado. A URL precisa ser um endereço público http ou https: uma URL que aponta para um endereço de rede privada, ou que usa outro esquema, é recusada.

Copie o arquivo para o armazenamento do Nodaro quando a URL for temporária, como um link assinado que expira, ou quando você quiser que o arquivo continue disponível:

curl -s -X POST https://app.nodaro.ai/v1/save-to-storage \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaUrl": "https://example.com/clip.mp4", "filename": "clip.mp4", "mediaType": "video"}'
# {"jobId":"…"}  poll the job; its output carries the stored file
const { jobId } = await client.media.saveToStorage({
  mediaUrl: 'https://example.com/clip.mp4',
  filename: 'clip.mp4',
  mediaType: 'video',
})
nodaro media save https://example.com/clip.mp4 --filename clip.mp4 --type video --watch

Em um workflow, passe a URL de um arquivo enviado para um nó Enviar imagem, Enviar vídeo ou Enviar áudio pelas entradas da execução. Os campos url de mídia dos nós de entrada sempre podem ser substituídos por uma execução. Veja Executar um workflow com novos valores de entrada.

Importar um vídeo de uma rede social

POST /v1/download-video importa para o seu armazenamento o vídeo por trás de um link para a página de um vídeo, ou de um link direto para um arquivo de vídeo. Envie a confirmação de direitos de conteúdo do link como confirmationId (veja Direitos de conteúdo). A rota responde com um downloadId, não com um ID de tarefa:

{ "url": "https://youtu.be/XXXX", "maxHeight": 720, "sectionStartSec": 30, "sectionEndSec": 90 }
  • maxHeight limita a resolução; omita o campo para obter a melhor disponível. sectionStartSec e sectionEndSec baixam só esse trecho do vídeo, com cerca de 3 segundos a mais em cada ponta, porque o corte cai nos quadros-chave. Envie os dois ou nenhum, e corte o resultado quando precisar de um corte exato. Com exactSection: true, o trecho é cortado exatamente nesse intervalo, sem margem.
  • Um vídeo sem faixa de som falha, a menos que você envie requireAudio: false.
  • Um link direto para um arquivo de vídeo pode ter no máximo 30 minutos e no máximo 10 GiB. O cabeçalho do arquivo é lido antes de qualquer download, e um arquivo acima de qualquer um dos limites responde na hora 422 media_too_long, 422 media_too_large ou 422 media_bitrate_implausible. O arquivo é verificado de novo depois do download. Um arquivo que não passa nessa verificação não é guardado, e a transmissão do progresso termina failed, com o motivo em error. Um link para a página de um vídeo em uma rede social não tem esse limite de duração, então importe um trecho de um vídeo longo.
  • Cada conta pode fazer 4 importações ao mesmo tempo. Uma quinta retorna 429 too_many_downloads.
  • GET /v1/download-video/progress/:downloadId transmite o progresso como server-sent events, cerca de duas vezes por segundo: { phase, percent, videoUrl?, thumbnailUrl?, error? }. A transmissão termina quando a importação fica completed, com o videoUrl armazenado, ou failed, com um error. O progresso só fica guardado por pouco tempo depois que a importação termina, então comece a lê-lo logo.
  • O vídeo pronto é salvo na sua biblioteca.

Para verificar um vídeo antes de importá-lo, POST /v1/video-metadata com { url } lê a duração, o tamanho e o título dele sem baixá-lo. No terminal: nodaro media download <url> --max-height 720 --watch e nodaro media metadata <url>. As outras ferramentas de mídia estão em Voz e mídia.

Cortar ou recortar um arquivo armazenado

POST /v1/media/process corta ou recorta um arquivo de vídeo ou de áudio armazenado. A rota é gratuita e responde na hora, sem tarefa:

{
  "sourceUrl": "https://…/interview.mp4",
  "type": "video",
  "trim": { "startTime": 12.5, "endTime": 48 },
  "crop": { "x": 0, "y": 0, "width": 1080, "height": 1080 }
}

A resposta é { "data": { url, thumbnailUrl, assetId, sizeBytes, mimeType, metadata } }. format define o formato de saída: mp4 ou webm para vídeo, mp3, wav, m4a ou aac para áudio. Com deleteSource: true, o arquivo de origem é removido depois, quando ele é seu e nada mais o usa, e assim o corte substitui o original. No SDK, chame client.media.process(input). Para cortar dentro de um workflow, use o nó Cortar vídeo, que custa créditos.

Importar uma imagem de um endereço da web

POST /v1/media/import-url com o corpo { "url": "https://…" } copia uma imagem de um endereço da web para o seu armazenamento. O endereço precisa ser http ou https e não pode ser privado, e a imagem pode ter até 20 MB. 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. 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.

A resposta é { "data": { url, thumbnailUrl, assetId, mimeType, sizeBytes, filename, width, height } }. Uma importação recusada responde 400 validation_error para um endereço ou um formato não aceito, e 422 fetch_failed quando o endereço não pode ser acessado. Ela responde 413 quando a imagem passa de 20 MB (file_too_large) ou o seu armazenamento está cheio (storage_limit_exceeded). No SDK, chame client.uploads.importUrl(url). O nó Enviar imagem usa essa importação quando você cola um link de imagem.

Descartar um arquivo de que você não precisa mais

POST /v1/media/discard com o corpo { "url": "https://…" } descarta um arquivo que você acabou de criar e de que não precisa mais. 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. Não é uma exclusão geral. O arquivo só é removido quando é seu e foi criado por /v1/download-video, /v1/media/process ou uma importação de URL. Ele também precisa ter menos de 24 horas, e nenhuma tarefa sua pode usá-lo, como saída ou como entrada, por exemplo o videoUrl de uma execução.

RespostaSignificado
{ "data": { "discarded": true } }O arquivo foi removido.
{ "data": { "discarded": false } }Não havia nada seu nesse endereço: o arquivo já não existe, ou não é seu.
409 not_discardableO arquivo não atende às condições acima. Nada foi alterado.

No SDK, chame client.media.discard({ url }).

A sua biblioteca de mídia

GET /v1/library lista a sua mídia, do mais novo para o mais antigo. Por padrão, lista os arquivos que você salvou na sua biblioteca mais a biblioteca compartilhada. Com owned=true, lista em vez disso todos os arquivos que são seus: envios e gerações, salvos ou não.

ParâmetroSignificado
typeall (o padrão), image, video ou audio.
qBusca: apenas os arquivos cujo nome contém todas as palavras de q, até 5 palavras, sem diferenciar maiúsculas de minúsculas. Cada caractere é comparado como ele mesmo, então %, _ e * não são curingas. Um q em branco não é busca, e q aceita até 200 caracteres. O nome anterior, search, ainda funciona.
ownedtrue lista todos os arquivos que são seus em vez da visão da biblioteca.
sourceApenas a mídia de uma origem: internal, mcp, app, cli, sdk, extension, web ou api. Os arquivos de antes de a origem ser registrada não têm origem, então só aparecem quando source é omitido.
limitTamanho da página, de 1 a 100. O padrão é 40.
cursorO nextCursor da página anterior.

A resposta é { data, nextCursor, totalCount }. Cada item traz id, type, filename, mimeType, sizeBytes, url, thumbnailUrl, metadata, isLibraryItem, uploadSource, source, sourceDetail, jobId e createdAt. jobId é a tarefa que criou o arquivo, ou null para um envio. nextCursor é null na última página, e totalCount, o número de arquivos que correspondem, vem apenas com a primeira página. Uma linha da biblioteca cujo arquivo guardado não existe mais não é listada nem contada, então todo item tem um url.

curl -s "https://app.nodaro.ai/v1/library?owned=true&type=image&q=poster" \
  -H "Authorization: Bearer $NODARO_API_KEY"

No SDK, chame client.library.list({ type: 'image', q: 'poster' }). A ferramenta MCP browse_uploads lê a visão owned=true, com a mesma busca por nome de arquivo no argumento search.

POST /v1/library/save-generated com { url, type } salva um arquivo na sua biblioteca. Um arquivo no armazenamento do Nodaro só é aceito quando é seu: uma das suas gerações, um arquivo que você enviou ou um arquivo na sua pasta de envios. Qualquer outro arquivo no armazenamento do Nodaro responde 403 forbidden, exista ele ou não. Um link para qualquer outro site é salvo como foi informado.

Para levar um usuário com login a um arquivo da biblioteca de arquivos do app, Meus arquivos, use um link para /library com um destes dois parâmetros de consulta:

LinkAbre
https://app.nodaro.ai/library?job=<jobId>O arquivo que essa tarefa criou: o jobId que a sua chamada de geração retornou.
https://app.nodaro.ai/library?asset=<assetId>Esse arquivo: um id de GET /v1/library?owned=true. Sem owned=true, a lista também contém itens da biblioteca compartilhada que Meus arquivos nunca mostra.
  • A página busca e depois mostra o arquivo. Ela mostra “Procurando o arquivo…”, depois rola até o arquivo, destaca-o e abre a prévia dele.
  • Ela procura entre os cerca de 1.000 arquivos mais novos do usuário. Um link para um arquivo mais antigo abre Meus arquivos sem ele.
  • Quando o arquivo não pode ser mostrado, uma mensagem curta diz o motivo, e a página abre normalmente. Os motivos: o id é desconhecido ou não é do usuário, a tarefa ainda está em execução, ou a tarefa falhou ou não criou nenhum arquivo. Quando a própria busca falha, a mensagem pede que o usuário tente o link de novo.
  • O parâmetro é removido do endereço depois de lido, então atualizar a página ou usar Voltar não abre o arquivo de novo.
  • Um usuário sem login entra primeiro e depois chega ao arquivo. Uma instalação auto-hospedada responde nos mesmos caminhos, no próprio endereço.

Enviar arquivos a partir de um assistente de IA

O servidor MCP oferece três jeitos de enviar arquivos, cada um para imagens, áudio e vídeo. Todos exigem o escopo assets:write.

JeitoFerramentasFunciona em
Seletor de arquivos no chatupload_image_widget, upload_audio_widget, upload_video_widgetClaude.ai na web. O seletor de imagens aceita até 10 arquivos.
Página de envio no navegadorrequest_image_upload, request_audio_upload, request_video_uploadTodos os clientes MCP. A ferramenta retorna uma página para abrir em um navegador e a URL pública final do arquivo.
URL de upload pré-assinadaprepare_image_upload, prepare_audio_upload, prepare_video_uploadClientes que conseguem executar comandos de shell, como Claude Code, Cursor ou Cline. Envie o arquivo com curl -X PUT --data-binary @file. Não funciona no Claude.ai web nem no Android.

Perguntas frequentes

Como envio um arquivo para o Nodaro pela API?

Envie POST /v1/upload como multipart form data, com o arquivo no campo file. A resposta traz a url do arquivo armazenado, que você pode passar para qualquer nó como imageUrl, videoUrl ou audioUrl.

Quais formatos de arquivo posso enviar?

Imagens em PNG, JPEG, WebP, GIF, AVIF, HEIC ou HEIF, vídeo em MP4, MOV, WebM ou AVI e áudio em MP3, WAV, M4A ou AAC, OGG, WebM ou FLAC. O POST /v1/upload aceita imagens de até 25 MB, vídeos de até 500 MB e áudios de até 50 MB. Um arquivo de vídeo ou de áudio mais longo vai pelas rotas de envio grande, com até 30 minutos e 10 GiB.

Preciso enviar um arquivo antes que um nó possa usá-lo?

Não. A maioria das rotas aceita diretamente uma URL pública http ou https. Envie o arquivo, ou copie-o com POST /v1/save-to-storage, quando a URL for privada ou temporária, ou quando você quiser que o Nodaro guarde uma cópia própria.

O que acontece quando o meu armazenamento está cheio?

O envio retorna 413, e o SDK lança StorageExceededError com o seu limite em details.quotaBytes. Exclua os arquivos de que você não precisa mais, ou libere espaço, e envie de novo.

Como envio a um usuário um link para um arquivo da biblioteca dele no Nodaro?

Use o link https://app.nodaro.ai/library?job= seguido do id da tarefa, ou ?asset= seguido de um id de GET /v1/library?owned=true. A página encontra o arquivo, rola até ele e abre a prévia.

Como os assistentes de IA enviam arquivos pelo MCP?

O servidor MCP oferece três jeitos: um seletor de arquivos no chat, uma página de envio no navegador e uma URL de upload pré-assinada para clientes que conseguem executar comandos de shell. Cada um existe para imagens, áudio e vídeo.

Última atualização

Nesta página