Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.viddyscribe.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://api.viddyscribe.com

​
Authentication

All API requests require an API key passed in the X-API-Key header. 
X-API-Key: vsk_your_api_key_here

​
Endpoints

​
Upload Endpoints

Upload Media

Upload by file, URL, or request a signed upload URL

Notify Upload Complete

Start verification after a signed upload finishes

Get Upload Status

Poll signed-upload verification status

​
Text Generation Endpoints

Generate Text

Generate text using a media_id, URL, or direct file upload

​
Audio Generation Endpoints

Generate Audio

Generate an audio track using a media_id, URL, or direct file upload

​
Video Generation Endpoints

Generate Video

Generate a video using a media_id, URL, or direct file upload

​
Results Endpoint

Get Results

Poll for job results and download outputs

​
Quick Example

1

Upload

curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@video.mp4"
2

Generate

curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "MEDIA_ID", "language": "en-US"}'
3

Get Results

curl "https://api.viddyscribe.com/enterprise/api/get_results?job_id=JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

​
Languages and Voices

For the full list of 53 supported language codes and 31 voice IDs, including which voices cover which languages, see Languages and Voices.

​
Video Categories

Auto • Educational Lecture • Educational Kids • Government Meeting • Documentary • Narrative Story • Social Media • Tutorial/How-To • Vlog • Commercial/Advertisement • News • Entertainment • Home Video • Video Call

​
Output Formats

Every generation endpoint returns the text descriptions in the response. Set format (default vtt) to choose how that text is serialized:
format valueDescription
jsonStructured array with timestamps and description text
vttWebVTT subtitles
srtSubRip subtitles
edlEdit Decision List for video editors
The audio endpoint additionally returns a WAV track and the video endpoint additionally returns an MP4. For text-only output, see the text endpoint.

​
Error Codes

CodeDescription
400Bad request - invalid parameters
401Unauthorized - invalid API key
403Forbidden - plan restriction or input limit
404Not found - media or job not found
409Conflict - media is not ready for generation or upload verification failed
415Unsupported media type - uploaded media is not a valid video
429Too many requests - rate, queue, concurrency, or plan limit exceeded
500Internal server error

​
Common Error Payloads

ErrorHTTP StatusDescription
no_video_stream415The uploaded file contains audio only or otherwise has no video stream. Upload a file with at least one video stream.
video_too_long403The submitted video exceeds the maximum duration allowed by the current plan.
file_too_large403The submitted file exceeds the maximum file size allowed by the current plan.
upload_not_ready409Returned in the code field when generation is requested for media whose upload verification is still in progress. Retry shortly.
upload_failed409Returned in the code field when generation is requested for media whose upload verification failed. Re-upload the media and try again.
plan_limit_exceeded429The current team allocation has been exhausted.
concurrency_limit_exceeded429Too many concurrent submissions are being validated for the current team. Retry after a short delay.
queue_limit_exceeded429Too many jobs are already queued for the current team allocation. Wait for some jobs to complete before submitting more.
rate_limit_exceeded429Too many requests for the current team allocation. Retry after the returned delay.

​
Job Failure Errors

When a job that was successfully accepted later fails during processing, polling the job (via /get_results) returns status: "failed" along with a stable error code and a human-readable message. Switch on the error code to handle failures programmatically; show message in your UI. 
{
  "job_id": "task_abc123xyz",
  "status": "failed",
  "error": "standard_ad_not_enough_gaps",
  "message": "Not enough silent gaps for Standard AD. Set auto_fit: false to place descriptions over dialogue, or switch to Extended AD."
}
ErrorDescription
standard_ad_not_enough_gapsThe video doesn’t contain long enough silent gaps for Standard AD. Set auto_fit: false to allow descriptions over dialogue, or retry the same media with the Extended AD workflow.
content_blockedThe content was flagged by the safety filter and can’t be processed.
no_video_streamThe video has no visual content (e.g. a black screen or audio-only file). Audio descriptions require visual content to describe. Do not retry with the same media.
voice_unavailableThe selected voice isn’t available for the requested language. Choose a different voice and try again.
internal_errorAn unexpected internal error occurred. Retry the job; contact support if it persists.
These codes are returned in the error field of /get_results for failed jobs and are stable across releases. Additional codes may be added in future; treat unknown codes as internal_error.

​
Rate Limits

Limits are enforced per team across all API keys. Enterprise plans can request custom allocations; contact support if you need higher throughput.

​
Rate Limit Exceeded Response

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "limit": 50,
  "remaining": 0,
  "reset": 1696272000,
  "retry_after": 15
}
The retry_after field indicates how many seconds to wait before retrying.

​
Need Help?

Support

Email our team

Dashboard

View usage