Skip to main content

​
API Key Authentication

All ViddyScribe Enterprise API endpoints require authentication using an API key passed in the X-API-Key header.
API keys are sensitive credentials. Keep them secure and never commit them to version control.

​
Getting Your API Key

Get in touch at hello@viddyscribe.com to obtain your API key. Your API key will look like this: 
vsk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz (THIS IS A SAMPLE)

​
Making Authenticated Requests

Include your API key in the X-API-Key header with every request: 
curl -X GET https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_123 \
  -H "X-API-Key: vsk_your_api_key_here"

​
Authentication Errors

​
401 Unauthorized
error
The API key is missing or invalid.
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
​
403 Forbidden
error
The API key is valid, but the request is blocked by a plan restriction or input limit.
{
  "error": "video_too_long",
  "message": "The submitted video exceeds the maximum duration allowed by your plan"
}
Common 403 errors:
  • feature_not_available - The requested feature is not enabled on the current plan
  • video_too_long - The submitted video exceeds the plan’s maximum duration
  • file_too_large - The submitted file exceeds the plan’s maximum file size
​
409 Conflict
error
The request is valid, but the referenced media is not yet in a usable state for generation.
{
  "error": "Upload is still in progress. Please retry shortly.",
  "code": "upload_not_ready",
  "upload_status": "processing"
}
Common 409 errors:
  • upload_not_ready - Upload is still in progress
  • upload_failed - Upload failed; re-upload the media and try again
​
429 Too Many Requests
error
The request was accepted syntactically, but blocked due to rate limiting, queue depth, or exhausted plan/ledger capacity.
{
  "error": "queue_limit_exceeded",
  "message": "You have 100 jobs queued. Please wait for some to complete before submitting more."
}
Common 429 errors:
  • rate_limit_exceeded - Too many requests were submitted in the current window
  • concurrency_limit_exceeded - Too many concurrent submissions are being validated
  • queue_limit_exceeded - Too many jobs are already queued
  • plan_limit_exceeded - No credits or usage capacity remain for the request
​
403 Feature Not Available
error
The requested feature or configuration option is not available on your current plan.
{
  "error": "feature_not_available",
  "message": "This feature is not available on your current plan. Contact hello@viddyscribe.com for access.",
  "plan_name": "Starter"
}

​
Best Practices

  • Use environment variables
  • Never hardcode keys in your source code
  • Don’t commit keys to version control
  • Use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.)
Periodically rotate your API keys to minimize security risks. Contact your admin to generate new keys.
Use separate API keys for development, staging, and production environments.
Keep track of your API usage to avoid hitting rate limits unexpectedly.