API für Video-Transkription und Notizen

Schnellstart

Diese Schritte bringen eine Datei von deiner Festplatte zu Transkript und Notizen. Du brauchst einen aktiven Basic- oder Plus-Tarif, ein Terminal und für den Beispiel-Client Python 3.12 oder neuer.

1. API-Schlüssel erstellen

Melde dich auf der Website an (zum Beispiel auf der Preisseite), öffne API-Schlüssel in der Kontoleiste, gib dem Schlüssel einen Namen und lege bei Bedarf ein Ablaufdatum fest. Kopiere den geheimen Schlüssel, sobald er erscheint: Er wird nur einmal angezeigt. Bis zu drei Schlüssel können gleichzeitig aktiv sein.

2. Schlüssel in einer Umgebungsvariable speichern

Halte den Schlüssel aus Quellcode, Kommandozeilenargumenten und Logs heraus. Die Beispiele lesen den Schlüssel aus VTN_API_KEY und die Basis-URL aus VTN_API_BASE.

export VTN_API_BASE="https://api.video-to-notes.com"
read -rs VTN_API_KEY && export VTN_API_KEY   # paste the key, press Enter

$env:VTN_API_BASE = "https://api.video-to-notes.com"
$env:VTN_API_KEY = Read-Host "API key" -MaskInput

3. Konto prüfen

Dieser Aufruf bestätigt, dass der Schlüssel funktioniert, und liefert deinen Tarif, deine verbleibenden Tarifsekunden, die unterstützten Formate und die aktuellen Limits.

# Sends the key through stdin, so it never appears in the process list.
vtn() {
  printf 'header = "Authorization: Bearer %s"\n' "$VTN_API_KEY" |
    curl -s --config - "$@"
}

vtn "$VTN_API_BASE/api/v1/account"

$headers = @{ Authorization = "Bearer $env:VTN_API_KEY" }
Invoke-RestMethod "$env:VTN_API_BASE/api/v1/account" -Headers $headers |
  ConvertTo-Json -Depth 5

4. Eine Datei transkribieren

Lade den Python-Beispiel-Client herunter. Er braucht nur die Standardbibliothek. Er lädt die Datei in Teilen hoch, startet den Auftrag, wartet auf das Ergebnis und speichert jede Ergebnisseite.

python client.py run meeting.mp4 --state meeting.state.json \
  --output meeting.jsonl --download meeting-files

Um nur einen Teil einer Aufnahme zu verarbeiten, gib --start und --end in Sekunden ab Dateibeginn an. --audio-language gibt einen Sprachhinweis und --notes-language wählt die Sprache der Notizen. Ohne diese Optionen wird die ganze Datei verarbeitet und die Sprachen werden automatisch erkannt.

python client.py run lecture.webm --state lecture.state.json \
  --start 30 --end 3630 --audio-language ru --notes-language en

Die Statusdatei speichert die Upload-ID und die Anfrage-Identität, niemals den Schlüssel. Bricht der Befehl ab, starte ihn mit derselben Statusdatei erneut: Er findet denselben Auftrag wieder und dir wird nichts doppelt berechnet. Verwende für jeden neuen Auftrag eine neue Statusdatei.

5. Ergebnisse lesen

meeting.jsonl enthält pro Zeile eine JSON-Ergebnisseite: Transkripttext mit Zeitangaben, Notizen in Markdown, Lücken und Warnungen. meeting-files enthält die Downloads, etwa das Transkript als TXT und die Notizen als Markdown, HTML und PDF. Der Client hat außerdem diese Befehle:

python client.py account
python client.py status JOB_ID
python client.py result JOB_ID --output results.jsonl --download files
python client.py cancel JOB_ID
python client.py resume JOB_ID

Lieber curl? Der Bash-Schnellstart führt dieselben Schritte für Upload, Auftrag und Ergebnis mit curl und jq aus.

bash quickstart.sh meeting.mp4

So funktioniert ein Auftrag

Jede Integration folgt denselben sechs Schritten. Die API-Referenz zeigt jeden Aufruf mit Beispielanfrage und Beispielantwort.

1. Konto prüfen. GET /api/v1/account liefert deinen Tarif, die verbleibenden Sekunden, die unterstützten Formate und die Limits.
2. Upload anlegen. POST /api/v1/uploads mit der Dateigröße in Bytes und der Dateiendung. Die Antwort nennt die Teilgröße und die Anzahl der Teile.
3. Teile hochladen. Hole signierte URLs über POST /api/v1/uploads/{upload_id}/parts, sende jeden Teil per HTTP-PUT direkt in den Speicher, bewahre jedes ETag auf und rufe dann POST /api/v1/uploads/{upload_id}/complete auf.
4. Auftrag starten. POST /api/v1/jobs mit der Upload-ID und einem Idempotency-Key-Header. Der Server prüft die echte Datei, plant die Arbeit und reserviert die Zeit in deinem Tarif.
5. Status abfragen. GET /api/v1/jobs/{job_id}, bis der Zustand endgültig ist; warte zwischen den Aufrufen mindestens poll_after_seconds.
6. Ergebnis lesen. GET /api/v1/jobs/{job_id}/result und folge next_cursor, bis der Wert null ist. Lade die in artifacts aufgeführten Dateien herunter, bevor ihre Links ablaufen.

Ein Auftrag endet als completed, completed_with_gaps, interrupted, cancelled, failed oder expired. charged_seconds zeigt, wie viel deines Tarifs der Auftrag verbraucht hat.

Best Practices

Diese Gewohnheiten schützen deine Schlüssel, verhindern doppelte Abrechnung und machen lange Aufträge zuverlässig.

Schlüssel geheim halten

• Rufe die API nur von einem Server oder Skript auf, das du kontrollierst. Lege einen Schlüssel niemals in Browser-Code, eine Mobil-App, eine URL oder die Versionsverwaltung.
• Lade den Schlüssel aus einer Umgebungsvariable oder einem Secret-Manager und halte ihn aus Logs, Fehlerberichten und Kommandozeilenargumenten heraus.
• Verwende einen Schlüssel pro Integration mit Ablaufdatum, damit du einen Schlüssel austauschen oder widerrufen kannst, ohne die anderen anzufassen.
• Zum Austauschen erstellst du den neuen Schlüssel, setzt ihn ein und widerrufst dann den alten. Bereits gestartete Aufträge laufen weiter.
• Wenn ein Schlüssel offengelegt worden sein könnte, etwa in einem Chat, einem Ticket oder einem Commit, widerrufe ihn sofort in der Ansicht API-Schlüssel.

Auftragserstellung wiederholbar machen

• Erzeuge für jeden neuen Auftrag einen zufälligen Idempotency-Key, etwa eine UUID, und speichere ihn mit der Upload-ID, bevor du die Anfrage sendest.
• Geht die Antwort verloren, sende dieselbe Anfrage mit demselben Schlüssel erneut. Du erhältst den ursprünglichen Auftrag zurück und zahlst nicht doppelt.
• Verwende einen Schlüssel nie für eine andere Datei oder andere Optionen: Die API antwortet dann mit 409 IDEMPOTENCY_CONFLICT.

Rücksichtsvoll abfragen und Limits beachten

• Warte zwischen Statusabfragen mindestens fünf Sekunden, und länger, wenn poll_after_seconds es verlangt.
• Warte bei 429 oder 503 auf den Header Retry-After oder error.retry_after_seconds und wiederhole die Anfrage dann mit etwas zufälliger Verzögerung.
• Wiederhole eine Anfrage unverändert nur, wenn error.retryable true ist. Andernfalls korrigiere zuerst die Anfrage.
• Ein Konto führt jeweils einen Upload und einen Auftrag gleichzeitig aus. Stelle deine Dateien in eine Warteschlange und sende die nächste, wenn der aktuelle Auftrag fertig ist.

Den Stundenverbrauch steuern

• Prüfe remaining_seconds, bevor du hochlädst. Ein Auftrag, der mehr Zeit braucht, als du hast, scheitert mit INSUFFICIENT_BALANCE; die API kürzt deine Auswahl nie, damit sie passt.
• Sende einen range, wenn du nur einen Teil einer Aufnahme brauchst. Berechnet wird nur das ausgewählte Audio.
• Brich Aufträge ab, die du nicht mehr brauchst. Fertige Teile bleiben verfügbar und nicht genutzte reservierte Zeit wird zurückgegeben.
• Brich Uploads ab, die du nicht verwenden wirst, damit der nächste Upload starten kann.

Vollständige Ergebnisse einsammeln

• Folge next_cursor, bis der Wert null ist. Eine Seite enthält höchstens 32 Einträge.
• Behandle gap-Einträge als Audio, das nicht verarbeitet werden konnte, nicht als Stille, und prüfe die warnings.
• Lade die Dateien in artifacts herunter, solange ihre Links gültig sind (bis zu zehn Minuten); rufe die Seite für neue Links erneut ab.
• Speichere, was du brauchst: Ergebnisdateien werden etwa 24 Stunden aufbewahrt, die Transkript-Wiederherstellung etwa 48 Stunden.
• Lies die Felder, die du brauchst, und ignoriere den Rest.

Häufige Fragen

Dateien und Beispiele

Die Beispiele und Vertragsdateien werden mit der Website veröffentlicht und entsprechen der Live-API.

• client.py: Python-3.12+-Beispiel-Client, nur Standardbibliothek
• quickstart.sh: Bash-Beispiel mit curl und jq
• openapi.json: OpenAPI-3.1-Beschreibung aller Endpunkte, mit Beispielen
• paid-api.schema.json: JSON Schema aller Anfragen und Antworten

Hilfe

Etwas unklar oder funktioniert nicht? Schreib uns und nenne die request_id aus der Fehlerantwort, die Uhrzeit und den Endpunkt. Schick uns niemals deinen API-Schlüssel.