Videos hochladen

Videos lädst du hoch, indem du eine PUT-Anfrage an den Endpoint /videos/upload sendest, um ein neues Video-Objekt anzulegen. In der Antwort erhältst du eine signierte S3-URL, über die du die Videodatei hochladen kannst.

Zum Erstellen eines Videos brauchst du die Berechtigung videos.create. Wenn du visibility auf public setzt, brauchst du außerdem videos.publish. Ohne publish wird das Video als private angelegt. Siehe Authentifizierung.

title ist erforderlich. Es wird getrimmt und auf 100 Zeichen gekürzt. Ein Update erlaubt 150 Zeichen. Siehe Video aktualisieren.

Der JSON-Body akzeptiert außerdem:

Feld	Hinweise
`description`	Maximal 2000 Zeichen.
`visibility`	`public` erfordert `videos.publish`. Sonst wird das Video als `private` gespeichert.
`categories`	Höchstens 10 Ids. Unbekannte Ids werden verworfen. Ein Key mit Scope, der keine Kategorien erhält, bekommt seine Scope-Kategorien zugewiesen, bis zu 10.
`tags`	Höchstens 20 Ids. Unbekannte Ids werden verworfen.
`language`	Locale der gesprochenen Sprache, zum Beispiel `de-DE`. Erforderlich, wenn `autoTranscribe` `true` ist.
`autoTranscribe`	KI-Transkription nach dem Encoding starten.
`customMetadata`	Flaches Schlüssel-Wert-Objekt. Siehe das Video-Objekt.
`duration`	Optionaler Hinweis in Sekunden. Das Encoding überschreibt ihn.
`fps`	Optionaler Hinweis. Das Encoding überschreibt ihn.
`orientation`	`landscape` oder `portrait`. Das Encoding überschreibt den Wert.
`useMultipart`	Liefert Kennungen für den Multipart Upload statt `signedUrl`.

Der JSON-Body hat kein Feld mimeType. Sende den MIME-Typ der Datei als Content-Type-Header beim Upload an die signierte URL im nächsten Schritt.

Video-Objekt anlegen

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

Hast du ein Video mit gesprochenem Inhalt und möchtest du die KI-Auto-Transkription direkt nach dem Video-Encoding starten, kannst du dazu zwei zusätzliche Parameter beim PUT-Request zum Anlegen des neuen Videos setzen:


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

Antwort

signedUrl läuft nach 1 Stunde ab. Für einen Multipart Upload setzt du useMultipart auf true. Die Antwort enthält dann multipartUpload statt signedUrl. Siehe Multipart Upload.


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

Videodatei hochladen

Lade deine Videodatei per PUT-Anfrage zu der signierten URL aus dem vorherigen Schritt hoch. Du musst den MIME-Typ der Datei als Content-Type-Header übergeben. Den MIME-Typ kannst du aus deiner lokalen Videodatei über das Datei-Input-Element auslesen.

Bei großen Dateien (über 100 MB) empfehlen wir stattdessen den Multipart Upload – zuverlässiger und für Dateien bis 60 GB. Du kannst auch die Uppy-Bibliothek nutzen – einfacher mit automatischem Chunking und Fortschrittsanzeige.

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

Encoding-Prozess

Nach dem Upload der Videodatei startet das Encoding. Je nach Dateigröße und Encoding-Komplexität kann das eine Weile dauern.

Den Encoding-Status pollst du mit GET /api/videos/[VIDEO_ID] wie im Abschnitt Video abrufen beschrieben. Ein Poll-Intervall von ein paar Sekunden reicht normalerweise aus. Während das Encoding läuft, ist status PROGRESSING und statusProgress ein Prozentwert von 0 bis 100.

Beispielfelder während des Encodings:


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

Ist das Encoding erfolgreich, wird status zu COMPLETE, statusProgress ist 100, und Wiedergabequellen sind unter src verfügbar.

Schlägt das Encoding fehl, wird status zu ERROR. Nutze errorCode für die programmatische Verarbeitung und errorMessage als lesbare Fallback-Meldung. Siehe Encoding-Status für den vollständigen Lebenszyklus, Statuswerte und Fehlercodes.

Alternativ kannst du video.updated-Webhooks abonnieren statt zu pollen. Fortschritts-Updates können während des Encodings häufig ausgelöst werden. Siehe Webhooks.