API Reference - ViddyScribe

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

Upload

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

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

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

14 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` value	Description
`json`	Structured array with timestamps and description text
`vtt`	WebVTT subtitles
`srt`	SubRip subtitles
`edl`	Edit 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

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

Common Error Payloads

Error	HTTP Status	Description
`no_video_stream`	`415`	The uploaded file contains audio only or otherwise has no video stream. Upload a file with at least one video stream.
`video_too_long`	`403`	The submitted video exceeds the maximum duration allowed by the current plan.
`file_too_large`	`403`	The submitted file exceeds the maximum file size allowed by the current plan.
`upload_not_ready`	`409`	Returned in the `code` field when generation is requested for media whose upload verification is still in progress. Retry shortly.
`upload_failed`	`409`	Returned in the `code` field when generation is requested for media whose upload verification failed. Re-upload the media and try again.
`plan_limit_exceeded`	`429`	The current team allocation has been exhausted.
`concurrency_limit_exceeded`	`429`	Too many concurrent submissions are being validated for the current team. Retry after a short delay.
`queue_limit_exceeded`	`429`	Too many jobs are already queued for the current team allocation. Wait for some jobs to complete before submitting more.
`rate_limit_exceeded`	`429`	Too 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."
}

Error	Description
`standard_ad_not_enough_gaps`	The 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_blocked`	The content was flagged by the safety filter and can’t be processed.
`no_video_stream`	The 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_unavailable`	The selected voice isn’t available for the requested language. Choose a different voice and try again.
`internal_error`	An 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

​Base URL

​Authentication

​Endpoints

​Upload Endpoints

Upload Media

Notify Upload Complete

Get Upload Status

​Text Generation Endpoints

Generate Text

​Audio Generation Endpoints

Generate Audio

​Video Generation Endpoints

Generate Video

​Results Endpoint

Get Results

​Quick Example

​Languages and Voices

​Video Categories

​Output Formats

​Error Codes

​Common Error Payloads

​Job Failure Errors

​Rate Limits

​Rate Limit Exceeded Response

​Need Help?

Support

Dashboard

Base URL

Authentication

Endpoints

Upload Endpoints

Text Generation Endpoints

Audio Generation Endpoints

Video Generation Endpoints

Results Endpoint

Quick Example

Languages and Voices

Video Categories

Output Formats

Error Codes

Common Error Payloads

Job Failure Errors

Rate Limits

Rate Limit Exceeded Response

Need Help?