API de descripción de video Documentación

Todas las solicitudes API requieren autenticación mediante token Bearer en el encabezado Authorization.

Authorization: Bearer nxt_your_api_key_here

Pruebe su integración webhook gratis usando nuestro entorno sandbox. Las tareas sandbox simulan el flujo de trabajo completo sin procesamiento de video real.

Beneficios del Sandbox

• Cuota diaria gratuita - no se requieren tokens
• Entregas webhook reales con firmas HMAC
• No se requiere URL de video
• Reproducción webhook para depuración

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

La API demo le permite integrar con un flujo de trabajo asíncrono real con entrega webhook antes de la producción. Úsela para validar el acceso directo a URL de video y el receptor webhook.

Endpoints

• POST /api/demo/v1/video-descriptions — crear tarea demo (solo URL directa)
• GET /api/demo/v1/video-descriptions/{job_id} — obtener estado/resultado
• POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — reproducir webhook reenviado a su receptor
• GET /api/demo/v1/webhook-secret — obtener secreto webhook para verificación de firma

Crear tarea demo (ejemplo)

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

Firmas webhook

La API demo reenvía webhooks a su URL usando los mismos encabezados de firma que la API principal: X-Nxt-Timestamp y X-Nxt-Signature. Use GET /api/demo/v1/webhook-secret para recuperar el secreto usado para verificación.

Cuerpo de solicitud

Respuesta

Devuelve 202 Accepted con ID de tarea.

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

Consulte el estado de la tarea. Útil para monitorear el progreso si los webhooks no son adecuados.

Estados de tarea

Todos los webhooks están firmados usando HMAC-SHA256. Verifique las firmas para garantizar autenticidad.

Encabezados de firma

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

Ejemplo de verificación (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)

Para videos privados, use el patrón Source Provider. Su endpoint actúa como intermediario de acceso, devolviendo URL pre-firmadas cuando nuestra API necesita recuperar el video.

Flujo

1. 1 Envíe una tarea con configuración source.provider
2. 2 Nuestra API llama a su endpoint con solicitud firmada
3. 3 Verifique la firma y devuelva la URL pre-firmada
4. 4 Nuestra API obtiene el video desde la URL pre-firmada

La API devuelve códigos de estado HTTP estándar con mensajes de error detallados.

El costo base por tarea exitosa es 1 token. La transcripción de audio es un complemento facturado por cada 10 segundos de audio muestreado. El costo final se informa en el campo webhook billing.token_cost.