Videobeschreibungs-API Dokumentation

Alle API-Anfragen erfordern Authentifizierung über Bearer-Token im Authorization-Header.

Authorization: Bearer nxt_your_api_key_here

Testen Sie Ihre Webhook-Integration kostenlos mit unserer Sandbox-Umgebung. Sandbox-Aufgaben simulieren den vollständigen Workflow ohne tatsächliche Videoverarbeitung.

Sandbox-Vorteile

• Kostenloses Tageskontingent - keine Tokens erforderlich
• Echte Webhook-Zustellungen mit HMAC-Signaturen
• Keine Video-URL erforderlich
• Webhook-Wiedergabe zum Debuggen

POST /v1/sandbox/video-descriptions

{
  "frames": 10,
  "webhook": {
    "url": "https://your-app.com/webhooks/video"
  },
  "client_context": {
    "lang": "en",
    "output_fields": ["title", "description", "tags"],
    "custom_instructions": "Focus on technical details"
  }
}

Die Demo-API ermöglicht die Integration mit einem echten asynchronen Workflow mit Webhook-Zustellung vor der Produktion. Verwenden Sie sie zur Validierung des direkten Video-URL-Zugriffs und Webhook-Empfängers.

Endpunkte

• POST /api/demo/v1/video-descriptions — Demo-Aufgabe erstellen (nur direkte URL)
• GET /api/demo/v1/video-descriptions/{job_id} — Status/Ergebnis abrufen
• POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — weitergeleiteten Webhook an Ihren Empfänger wiedergeben
• GET /api/demo/v1/webhook-secret — Webhook-Secret zur Signaturüberprüfung abrufen

Demo-Aufgabe erstellen (Beispiel)

curl -X POST https://your-portal.com/api/demo/v1/video-descriptions \
  -H "X-API-Key: demo_your_demo_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "direct_url",
      "url": "https://example.com/video.mp4"
    },
    "frames": 10,
    "webhook": {
      "url": "https://your-app.com/webhooks/demo"
    },
    "client_context": {
      "lang": "en",
      "output_fields": ["title", "description", "tags"],
      "custom_instructions": "Make the description more detailed"
    }
  }'

Webhook-Signaturen

Die Demo-API leitet Webhooks an Ihre URL weiter und verwendet die gleichen Signatur-Header wie die Haupt-API: X-Nxt-Timestamp und X-Nxt-Signature. Verwenden Sie GET /api/demo/v1/webhook-secret, um das zur Überprüfung verwendete Secret abzurufen.

Anforderungstext

Antwort

Gibt 202 Accepted mit Aufgaben-ID zurück.

{
  "job_id": "01HXYZ123ABC",
  "status": "queued"
}

Aufgabenstatus abfragen. Nützlich zur Überwachung des Fortschritts, wenn Webhooks nicht geeignet sind.

Aufgabenstatus

Alle Webhooks sind mit HMAC-SHA256 signiert. Überprüfen Sie Signaturen, um Authentizität sicherzustellen.

Signatur-Header

X-Nxt-Timestamp: 1707400000
X-Nxt-Signature: sha256=abc123def456...

Überprüfungsbeispiel (Python)

import hmac
import hashlib

def verify_webhook(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    # Signature header format: "sha256="
    expected_sig = signature_header.removeprefix("sha256=")
    message = raw_body + timestamp.encode()
    computed = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, expected_sig)

Verwenden Sie für private Videos das Source-Provider-Muster. Ihr Endpunkt fungiert als Zugriffsvermittler und gibt vorsignierte URLs zurück, wenn unsere API das Video abrufen muss.

Ablauf

1. 1 Sie senden eine Aufgabe mit source.provider-Konfiguration
2. 2 Unsere API ruft Ihren Endpunkt mit signierter Anfrage auf
3. 3 Sie überprüfen die Signatur und geben die vorsignierte URL zurück
4. 4 Unsere API ruft das Video von der vorsignierten URL ab

Die API gibt Standard-HTTP-Statuscodes mit detaillierten Fehlermeldungen zurück.

Die Basiskosten pro erfolgreicher Aufgabe betragen 1 Token. Audio-Transkription ist ein Add-on, das pro 10 Sekunden gesampletem Audio abgerechnet wird. Die endgültigen Kosten werden im Webhook-Feld billing.token_cost gemeldet.