Envio de 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

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

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

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.

Quando um envio é recusado

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 (Upload Image), Enviar vídeo (Upload Video) ou Enviar áudio (Upload Audio) 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 um vídeo do YouTube, TikTok, Instagram, X ou Facebook, ou de um link direto para um arquivo de vídeo. A rota responde com um downloadId, não com um ID de job:

{ "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.
• Um vídeo sem faixa de som falha, a menos que você envie requireAudio: false.
• 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 job:

{
  "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 (Trim Video), que custa créditos.

Listar a sua mídia armazenada

GET /v1/library retorna as suas imagens, vídeos e áudios armazenados, com um resumo do seu armazenamento. Filtre com type (image, video ou audio) e pagine com limit e cursor. No SDK, chame client.library.list({ type: 'image' }).

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.