Caricamento dei video

Il caricamento dei video avviene inviando una richiesta PUT all’endpoint /videos/upload per creare un nuovo oggetto video. Riceverai una risposta con un URL S3 firmato su cui caricare il file video.

Creare un video richiede il permesso videos.create. Impostare visibility su public richiede anche videos.publish. Senza publish, il video viene creato come private. Vedi Autenticazione.

title è obbligatorio. Viene ripulito dagli spazi e tagliato a 100 caratteri. Un aggiornamento consente 150 caratteri. Vedi Aggiornare un video.

Il body JSON accetta anche:

Campo	Note
`description`	Massimo 2000 caratteri.
`visibility`	`public` richiede `videos.publish`. Altrimenti il video viene salvato come `private`.
`categories`	Al massimo 10 id. Gli id sconosciuti vengono scartati. Se una chiave con ambito non riceve categorie, le vengono assegnate le categorie dell’ambito, fino a 10.
`tags`	Al massimo 20 id. Gli id sconosciuti vengono scartati.
`language`	Locale della lingua parlata, per esempio `de-DE`. Obbligatorio quando `autoTranscribe` è `true`.
`autoTranscribe`	Avvia la trascrizione IA dopo la codifica.
`customMetadata`	Oggetto chiave-valore piatto. Vedi l’oggetto video.
`duration`	Suggerimento opzionale in secondi. La codifica lo sovrascrive.
`fps`	Suggerimento opzionale. La codifica lo sovrascrive.
`orientation`	`landscape` o `portrait`. La codifica lo sovrascrive.
`useMultipart`	Restituisce gli identificatori del multipart upload al posto di `signedUrl`.

Il body JSON non ha un campo mimeType. Invia il MIME type del file come header Content-Type nel caricamento sull’URL firmato, al passaggio successivo.

Crea l’oggetto video

CURL


curl -X PUT https://app.ignitevideo.cloud/api/videos/upload \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Your video title", "visibility": "private" | "public"}'

JavaScript / Node.js


const data = {
  "title": "Your video title", // trimmed, max 100 characters
  "visibility": "private" | "public", // optional
  "description": "Optional description",
  "categories": ["category-id", "..."], // optional
  "tags": ["tag-id", "..."], // optional
  "customMetadata": { "externalId": "celum-123" }, // optional
  "duration": 90, // optional, seconds
  "fps": 25, // optional
  "orientation": "landscape" // optional: "landscape" | "portrait"
}
const response = await fetch(`https://app.ignitevideo.cloud/api/videos/upload`, {
method: 'PUT',
body: JSON.stringify(data),
headers: {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json'
}
});

PHP


$client = new GuzzleHttp\Client();
$data = [
  "title" => "Your video title", // trimmed, max 100 characters
  "visibility" => "private" | "public", // optional
  "description" => "Optional description",
  "categories" => ["category-id", "..."], // optional
  "tags" => ["tag-id", "..."], // optional
  "customMetadata" => ["externalId" => "celum-123"], // optional
  "duration" => 90, // optional, seconds
  "fps" => 25, // optional
  "orientation" => "landscape" // optional: "landscape" | "portrait"
];
 
$response = $client->request('PUT', 'https://app.ignitevideo.cloud/api/videos/upload', [
'body' => json_encode($data),
'headers' => [
  'Authorization' => 'Bearer YOUR_TOKEN',
  'Content-Type' => 'application/json'
]
]);

Se hai un video con contenuto parlato e vuoi avviare la trascrizione automatica IA subito dopo la codifica del video, puoi farlo impostando due parametri aggiuntivi nella richiesta PUT per creare il nuovo video:


{ 
  ...,
  "language": string, // "de-DE" | "..."  locale of the spoken language
  "autoTranscribe": true
}

Risposta

signedUrl scade dopo 1 ora. Per un upload multipart, imposta useMultipart su true. La risposta contiene allora multipartUpload al posto di signedUrl. Vedi Multipart upload.


{
  "videoId": "[VIDEO_ID]",
  "title": "Your video title",
  "signedUrl": "[SIGNED_URL]"
}

Carica il file video

Carica il tuo file video con una richiesta PUT all’URL firmato restituito nel passaggio precedente. Devi passare il mime type del file come header Content-Type. Puoi ottenere il mime type dal tuo file video locale tramite l’elemento file input.

Per i file di grandi dimensioni (oltre 100MB), consigliamo di usare il multipart upload, che offre maggiore affidabilità e supporta file fino a 60GB. Puoi anche usare la libreria Uppy per un’implementazione più semplice con chunking automatico e monitoraggio dell’avanzamento.

CURL


curl -X PUT [SIGNED_URL] \
  -H "Content-Type: [MIME_TYPE]" \
  --data-binary "@[PATH_TO_VIDEO_FILE]"

JavaScript / Node.js


const response = await fetch([SIGNED_URL], {
  method: 'PUT',
  body: [VIDEO_FILE],
  headers: {
    'Content-Type': [MIME_TYPE]
  }
});

PHP


$client = new GuzzleHttp\Client();
$response = $client->request('PUT', [SIGNED_URL], [
  'body' => [VIDEO_FILE],
  'headers' => [
    'Content-Type' => [MIME_TYPE]
  ]
]);

Processo di codifica

Dopo il caricamento del file video, inizia la codifica. Questo processo può richiedere del tempo, a seconda della dimensione del video e della complessità della codifica.

Interroga lo stato di codifica con GET /api/videos/[VIDEO_ID] come descritto in ottenere video. Un intervallo di polling di pochi secondi di solito è sufficiente. Mentre la codifica è in corso, status è PROGRESSING e statusProgress è una percentuale da 0 a 100.

Esempio di campi durante la codifica:


{
  "id": "[VIDEO_ID]",
  "status": "PROGRESSING",
  "statusProgress": 36,
  "errorCode": null,
  "errorMessage": null
}

Quando la codifica ha successo, status diventa COMPLETE, statusProgress è 100 e le sorgenti di riproduzione sono disponibili in src.

Quando la codifica fallisce, status diventa ERROR. Usa errorCode per la gestione programmatica e errorMessage come fallback leggibile. Vedi Stato di codifica per il ciclo di vita completo, i valori di stato e i codici di errore.

Puoi anche iscriverti ai webhook video.updated invece di fare polling. Gli aggiornamenti di progresso possono scattare spesso durante la codifica. Vedi Webhooks.