Video Description API Documentation

All API requests require authentication via Bearer token in the Authorization header.

Authorization: Bearer nxt_your_api_key_here

Test your webhook integration for free using our sandbox environment. Sandbox jobs simulate the full workflow without actual video processing.

Sandbox Benefits

• Free daily quota - no tokens required
• Real webhook deliveries with HMAC signatures
• No video URL required
• Webhook replay for debugging

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

Demo API lets you integrate against a real async workflow with webhook delivery before you go live. Use it to validate your direct video URL access and webhook receiver.

Endpoints

• POST /api/demo/v1/video-descriptions — create a demo job (direct URL only)
• GET /api/demo/v1/video-descriptions/{job_id} — get status/result
• POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — replay forwarded webhook to your receiver
• GET /api/demo/v1/webhook-secret — get webhook secret for signature verification

Create demo job (example)

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 signatures

Demo API forwards webhooks to your URL using the same signature headers as the main API: X-Nxt-Timestamp and X-Nxt-Signature. Use GET /api/demo/v1/webhook-secret to retrieve the secret used for verification.

Request Body

Response

Returns 202 Accepted with job ID.

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

Poll job status. Useful for monitoring progress if webhooks aren't suitable.

Job Statuses

All webhooks are signed using HMAC-SHA256. Verify signatures to ensure authenticity.

Signature Headers

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

Verification Example (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)

For private videos, use the Source Provider pattern. Your endpoint acts as an access broker, returning presigned URLs when our API needs to fetch video.

Flow

1. 1 You submit job with source.provider config
2. 2 Our API calls your endpoint with signed request
3. 3 You verify signature and return presigned URL
4. 4 Our API fetches video from presigned URL

The API returns standard HTTP status codes with detailed error messages.

Base cost per successful job is 1 token. Audio transcription is an add-on billed per 10 seconds of sampled audio. Final cost is reported in the webhook billing.token_cost field.