videoservice

POST/video/convertX-Api-Key

Converti e comprimi

Transcodifica il video nel formato scelto. Restituisce il file convertito, con gli header che dicono quanto si è risparmiato.

Input accettati. video nel corpo grezzo, multipart file, o JSON {"video_base64": "..."}.

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  --data-binary @filmato.avi \
  "http://video.cmisolutions.it:3004/video/convert?format=mp4&crf=23&maxw=1280" -o filmato.mp4

FileMaker

Set Variable [ $video ; value: Video::File ]

Insert from URL [
    Select ; With dialog: Off ; Target: Video::Convertito ;
    "http://video.cmisolutions.it:3004/video/convert?format=mp4&maxw=1280" ;
    cURL options: "--data-binary @$video --max-time 3000 "
      & "-H \"X-Api-Key: " & $$API_KEY & "\""
]

Risposta

Il video convertito, con gli header X-Original-Bytes, X-Output-Bytes, X-Saved-Pct, X-Seconds, X-In-Codec/X-Out-Codec, X-In-Size/X-Out-Size, X-Duration-Sec, X-Filename.

Da sapere

• ⚠️ Serve --max-time alto nelle opzioni cURL di FileMaker: la conversione dura minuti e il default taglia prima. Se il Target è una variabile e non un campo container, aggiungere anche --FM-return-container-variable (altrimenti errore 507).
• Riscontro su un AVI di collaudo (1280x720, 8s, 1,8 MB): verso MP4 −86%; con maxw=640 −90%; senza audio −93%. Su materiale reale i numeri cambiano, ma l'ordine di grandezza è quello.
• maxw è la leva più efficace, molto più del crf: dimezzare la larghezza taglia i pixel a un quarto.
• Il tetto di caricamento è 4 GB, molto più alto degli altri servizi. Il corpo non viene tenuto in memoria: si scrive a blocchi su disco.
• Un transcode occupa un worker per tutta la sua durata, e i worker sono 2: due conversioni pesanti in parallelo saturano il servizio. È il motivo per cui la conversione video vive su una porta separata dagli altri servizi.
• Oltre 3000 secondi la conversione viene interrotta con un 504: video troppo lungo, o preset troppo lento.
• Nome del file: FileMaker lo legge dal Content-Disposition; senza, deposita un .dat anonimo nel contenitore. Con ?filename= (o inviando in multipart, che porta con sé il nome) il contenitore riceve il nome giusto. Gli accenti sono gestiti: filename= resta ASCII per i client vecchi e filename* porta il nome completo. Un nome con percorso (../../etc/passwd) viene ridotto al solo nome del file.

POST/video/infoX-Api-Key

Informazioni su un video

Durata, codec, risoluzione, fps e audio senza convertire: utile per decidere se e come comprimere, o per popolare dei campi.

Input accettati. come /video/convert.

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  --data-binary @filmato.avi "http://video.cmisolutions.it:3004/video/info" 

Risposta

JSON: durata_sec, bytes, bitrate, contenitore, video_codec, larghezza, altezza, fps, audio_codec, audio_canali.

Da sapere

• Il video viene comunque caricato per intero (ffprobe legge il file), quindi su file grandi la chiamata non è istantanea.

—Autenticazionesenza chiave

Come funzionano le chiavi

Una chiave = un soggetto (un database FileMaker, uno script, n8n). Ogni chiave porta l'elenco dei servizi su cui è abilitata, quindi la stessa chiave può valere su più servizi — ed è quello che vuoi: così le statistiche attribuiscono tutto il consumo a un'unica riga. Non condividere una chiave fra due soggetti: perderesti proprio l'informazione per cui l'hai creata. Le chiavi le gestisce l'amministratore: se te ne serve una, o la tua non funziona più, chiedila a lui.

cURL

# su ogni POST di lavoro
-H "X-Api-Key: cmi_xxxxxxxxxxxx"

# in FileMaker, tenendo la chiave in una variabile globale sola:
"-H \"X-Api-Key: " & $$API_KEY & "\"" 

Risposta

Se la chiave manca o è errata: 401 con un messaggio esplicito (mancante, non riconosciuta, revocata, non abilitata per questo servizio).

Da sapere

• Restano aperti senza chiave: /health e la pagina di test su /.
• Revoche e nuove chiavi hanno effetto immediato, senza riavviare i servizi.
• Oltre ai servizi, una chiave può essere ristretta ai singoli endpoint. Se è abilitata al servizio ma non a quella rotta la risposta è 403 (non 401: la chiave è valida, manca il permesso). Le restrizioni si impostano dal pannello di amministrazione e valgono subito.
• Ogni risposta porta X-Esito: ok|errore e X-Status. Servono da FileMaker: Insert from URL NON fallisce sugli errori HTTP — Get(LastError) resta 0 e il corpo dell'errore finisce nel contenitore, sovrascrivendo l'allegato buono. Con --dump-header $h si controlla l'esito prima di scrivere sul campo. Regola d'oro: mandare il risultato in una variabile, verificare, e solo allora fare Set Field.
• Nome del file restituito: gli endpoint che restituiscono un file accettano ?filename=. Senza, si usa il nome originale se l'invio è multipart (che lo porta con sé); con --data-binary il nome si perde, quindi lì il parametro serve. L'estensione è sempre quella d'uscita, sostituita e non appesa. Il nome è anche nell'header X-Filename.

GET/healthsenza chiave

Stato del servizio

Sonda di vita, aperta e non contabilizzata: un check ogni minuto non sporca le statistiche.

cURL

curl http://video.cmisolutions.it:3004/health

Risposta

JSON con status, service, la versione della libreria e auth (se l'obbligo di chiave è attivo).