Télécharger des vidéos

Pour télécharger une vidéo, envoie une requête PUT à l’endpoint /videos/upload afin de créer un nouvel objet vidéo. Tu recevras une réponse contenant une URL S3 signée pour télécharger le fichier vidéo.

La création d’une vidéo nécessite la permission videos.create. Définir visibility sur public nécessite aussi videos.publish. Sans publish, la vidéo est créée en private. Voir Authentification.

title est obligatoire. Il est nettoyé (espaces retirés), puis coupé à 100 caractères. Une mise à jour autorise 150 caractères. Voir Mettre à jour une vidéo.

Le corps JSON accepte aussi :

Champ	Notes
`description`	2000 caractères maximum.
`visibility`	`public` nécessite `videos.publish`. Sinon, la vidéo est enregistrée en `private`.
`categories`	10 ids maximum. Les ids inconnus sont retirés. Une clé avec périmètre qui ne reçoit aucune catégorie se voit assigner les catégories de son périmètre, jusqu’à 10.
`tags`	20 ids maximum. Les ids inconnus sont retirés.
`language`	Locale de la langue parlée, par exemple `de-DE`. Obligatoire lorsque `autoTranscribe` vaut `true`.
`autoTranscribe`	Lance la transcription IA après l’encodage.
`customMetadata`	Objet clé-valeur plat. Voir l’objet vidéo.
`duration`	Indication optionnelle en secondes. L’encodage l’écrase.
`fps`	Indication optionnelle. L’encodage l’écrase.
`orientation`	`landscape` ou `portrait`. L’encodage l’écrase.
`useMultipart`	Renvoie les identifiants de téléchargement multipart à la place de `signedUrl`.

Le corps JSON n’a pas de champ mimeType. Envoie le type MIME du fichier dans l’en-tête Content-Type lors du téléchargement vers l’URL signée, à l’étape suivante.

Créer l’objet vidéo

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'
]
]);

Si ta vidéo contient de la parole et que tu veux lancer la transcription automatique par IA juste après l’encodage de la vidéo, tu peux le faire en ajoutant deux paramètres supplémentaires lors de la requête PUT pour créer la nouvelle vidéo :


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

Réponse

signedUrl expire après 1 heure. Pour un téléchargement multipart, définis useMultipart sur true. La réponse contient alors multipartUpload à la place de signedUrl. Voir Téléchargement multipart.


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

Télécharger le fichier vidéo

Envoie ton fichier vidéo en requête PUT vers l’URL signée renvoyée à l’étape précédente. Tu dois indiquer le type MIME du fichier dans l’en-tête Content-Type. Tu peux obtenir le type MIME depuis ton fichier vidéo local via l’élément input de type fichier.

Pour les gros fichiers (plus de 100 Mo), nous recommandons d’utiliser plutôt le téléchargement multipart, plus fiable et prenant en charge des fichiers jusqu’à 60 Go. Tu peux aussi utiliser la bibliothèque Uppy pour une implémentation plus simple avec découpage automatique et suivi de progression.

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]
  ]
]);

Processus d’encodage

Une fois le téléchargement du fichier vidéo terminé, l’encodage démarre. Ce processus peut prendre du temps, selon la taille de la vidéo et la complexité de l’encodage.

Interroge le statut d’encodage avec GET /api/videos/[VIDEO_ID] comme décrit dans obtenir la vidéo. Un intervalle de sondage de quelques secondes suffit généralement. Pendant l’encodage, status vaut PROGRESSING et statusProgress est un pourcentage de 0 à 100.

Exemple de champs pendant l’encodage :


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

Si l’encodage réussit, status devient COMPLETE, statusProgress vaut 100, et les sources de lecture sont disponibles sous src.

Si l’encodage échoue, status devient ERROR. Utilise errorCode pour le traitement programmatique et errorMessage comme repli lisible. Voir Statut d’encodage pour le cycle de vie complet, les valeurs de statut et les codes d’erreur.

Tu peux aussi t’abonner aux webhooks video.updated au lieu d’interroger l’API. Les mises à jour de progression peuvent se déclencher souvent pendant l’encodage. Voir Webhooks.