API de description vidéo Documentation

Toutes les requêtes API nécessitent une authentification via jeton Bearer dans l'en-tête Authorization.

Authorization: Bearer nxt_your_api_key_here

Testez votre intégration webhook gratuitement en utilisant notre environnement sandbox. Les tâches sandbox simulent le flux de travail complet sans traitement vidéo réel.

Avantages du Sandbox

• Quota quotidien gratuit - aucun jeton requis
• Livraisons webhook réelles avec signatures HMAC
• Aucune URL vidéo requise
• Rejeu webhook pour débogage

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"
  }
}

L'API démo vous permet d'intégrer un flux de travail asynchrone réel avec livraison webhook avant la mise en production. Utilisez-la pour valider l'accès direct à l'URL vidéo et le récepteur webhook.

Endpoints

• POST /api/demo/v1/video-descriptions — créer une tâche démo (URL directe uniquement)
• GET /api/demo/v1/video-descriptions/{job_id} — obtenir le statut/résultat
• POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — rejouer le webhook transmis à votre récepteur
• GET /api/demo/v1/webhook-secret — obtenir le secret webhook pour vérification de signature

Créer une tâche démo (exemple)

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"
    }
  }'

Signatures webhook

L'API démo transmet les webhooks à votre URL en utilisant les mêmes en-têtes de signature que l'API principale : X-Nxt-Timestamp et X-Nxt-Signature. Utilisez GET /api/demo/v1/webhook-secret pour récupérer le secret utilisé pour la vérification.

Corps de la requête

Réponse

Retourne 202 Accepted avec l'ID de la tâche.

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

Interrogez le statut de la tâche. Utile pour surveiller la progression si les webhooks ne conviennent pas.

Statuts de tâche

Tous les webhooks sont signés en utilisant HMAC-SHA256. Vérifiez les signatures pour garantir l'authenticité.

En-têtes de signature

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

Exemple de vérification (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)

Pour les vidéos privées, utilisez le modèle Source Provider. Votre endpoint agit comme courtier d'accès, retournant des URL pré-signées lorsque notre API a besoin de récupérer la vidéo.

Flux

1. 1 Vous soumettez une tâche avec configuration source.provider
2. 2 Notre API appelle votre endpoint avec requête signée
3. 3 Vous vérifiez la signature et retournez l'URL pré-signée
4. 4 Notre API récupère la vidéo depuis l'URL pré-signée

L'API retourne des codes de statut HTTP standard avec messages d'erreur détaillés.

Le coût de base par tâche réussie est de 1 jeton. La transcription audio est un supplément facturé par tranche de 10 secondes d'audio échantillonné. Le coût final est rapporté dans le champ webhook billing.token_cost.