# API Introduction Source: https://docs.viddyscribe.com/api-introduction ViddyScribe Enterprise API overview, outputs, parameters, and endpoints. ViddyScribe supports two audio description types, each with different output formats: | AD Type | Outputs | | ---------------------------------------------------------------- | ------------------ | | **Standard AD** (no pauses) descriptions placed in dialogue gaps | Text, Audio, Video | | **Extended AD** (with pauses) descriptions added with pauses | Text, Video | For a deeper breakdown of when to choose each mode, see [Standard AD vs Extended AD](/standard-vs-extended-ad).
```vtt theme={null} WEBVTT 1 00:00:00.000 --> 00:00:02.000 A woman with long dark hair, wearing a pink cardigan, sits on a sofa and speaks to the camera. 2 00:00:02.570 --> 00:00:04.570 A mechanic in blue gloves measures a car's brake disc. 3 00:00:05.370 --> 00:00:07.370 The mechanic removes a wheel from a silver car, which is propped up on a jack; a blue RepairSmith van is parked in front of a house, next to the car. 4 00:00:09.290 --> 00:00:11.290 The woman looks at a laptop displaying the RepairSmith website. 5 00:00:16.000 --> 00:00:18.000 The laptop screen shows a 'Free Instant Quote' for car repair. The woman picks up her phone from a table; a RepairSmith notification displays on the smartphone. 6 00:00:22.565 --> 00:00:24.565 A mechanic in a black uniform and blue gloves steps out of the RepairSmith van; the woman in the pink cardigan speaks to the camera. 7 00:00:24.565 --> 00:00:26.565 Text appears: 'Book Today. Get $25 off with code HULU at RepairSmith.com'. ```
```vtt theme={null} WEBVTT 1 00:00:00.000 --> 00:00:02.000 A woman with long dark hair, wearing a pink cardigan, sits on a sofa and speaks to the camera. 2 00:00:02.570 --> 00:00:04.570 A mechanic in blue gloves measures a car's brake disc. 3 00:00:05.370 --> 00:00:07.370 The mechanic removes a wheel from a silver car, which is propped up on a jack; a blue RepairSmith van is parked in front of a house, next to the car. 4 00:00:09.290 --> 00:00:11.290 The woman looks at a laptop displaying the RepairSmith website. 5 00:00:16.000 --> 00:00:18.000 The laptop screen shows a 'Free Instant Quote' for car repair. The woman picks up her phone from a table; a RepairSmith notification displays on the smartphone. 6 00:00:22.565 --> 00:00:24.565 A mechanic in a black uniform and blue gloves steps out of the RepairSmith van; the woman in the pink cardigan speaks to the camera. 7 00:00:24.565 --> 00:00:26.565 Text appears: 'Book Today. Get $25 off with code HULU at RepairSmith.com'. ```
## How It Works Upload media files or provide a URL. We support all major video formats. Choose configuration options such as audio description (AD) type, language, format, and video category. Poll for completion or use webhooks. ## Quick Links Get started in 5 minutes Explore all endpoints Secure your requests ## Understand the parameters * **Standard AD** — Fits descriptions into existing no-speech gaps. Video runtime stays the same; some elements may go undescribed if there's no room. * **Extended AD** — Briefly pauses the video to make room for fuller descriptions. Runtime increases. See [Standard AD vs Extended AD](/standard-vs-extended-ad) for guidance on choosing. Set `language` (BCP-47 code, default `en-US`) on any generation request to control narration locale. ViddyScribe supports 53 languages including English variants, Spanish, French, German, Hindi, Mandarin, Arabic, and more. See the full list in [Languages and Voices](/api-reference/voices). Set `voice` on audio and video generation requests to pick the narrator (default `Achernar`). 31 voices are available (15 female, 16 male). Most cover all 53 languages; one extra `Robotic` voice is English-only. See the full list in [Languages and Voices](/api-reference/voices). Provide custom instructions to guide the AI for specific terminology, style preferences, or focus areas. Every generation endpoint returns the text descriptions in the response. Set `format` (default `vtt`) to choose how that text is serialized: * `json` — structured array with timestamps and description text * `vtt` — WebVTT subtitles * `srt` — SubRip subtitles * `edl` — Edit Decision List for video editors The [audio endpoint](/api-reference/processing/generate-audio-description-audio) additionally returns a WAV track and the [video endpoint](/api-reference/processing/generate-audio-description-video) additionally returns an MP4. For text-only output, see the [text endpoint](/api-reference/processing/generate-audio-description-text). ## API Endpoints ### Upload Endpoints | Endpoint | Method | Description | | ------------------------------------------------------------------- | ------ | ------------------------------------ | | [`/enterprise/api/upload_media`](/api-reference/media/upload-media) | POST | Upload video via File or URL (Input) | ### Generation Endpoints | Endpoint | Method | Description | | ------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------ | | [`/enterprise/api/generate_ad_text`](/api-reference/processing/generate-audio-description-text) | POST | Generate text-only descriptions (Input: media\_id, url, file) | | [`/enterprise/api/generate_ad_audio`](/api-reference/processing/generate-audio-description-audio) | POST | Generate audio-only track with text (Input: media\_id, url, file) | | [`/enterprise/api/generate_ad_video`](/api-reference/processing/generate-audio-description-video) | POST | Generate video with descriptions, and text (Input: media\_id, url, file) | ### Results Endpoint | Endpoint | Method | Description | | ----------------------------------------------------------------------- | ------ | ----------------------------------------- | | [`/enterprise/api/get_results`](/api-reference/results/get-job-results) | GET | Get results (Input: media\_id, url, file) | ## Need Help? Get in touch with our support team Explore all available endpoints # Get signed upload status Source: https://docs.viddyscribe.com/api-reference/media/get-signed-upload-status /openapi.yaml get /enterprise/api/get_upload_status Return the current verification status for a media item uploaded via the signed upload flow. Use this to confirm the upload is ready before calling a generation endpoint with `media_id`. # Get signed upload status Source: https://docs.viddyscribe.com/api-reference/media/get-upload-status get /enterprise/api/get_upload_status Return the current verification status for a media item uploaded via the signed upload flow. Use this to confirm the upload is ready before calling a generation endpoint with `media_id`. ## Usage Example Poll this endpoint after `notify_upload_complete` until the upload has finished verification and the media is ready for generation. ```bash theme={null} curl "https://api.viddyscribe.com/enterprise/api/get_upload_status?media_id=550e8400-e29b-41d4-a716-446655440000&gcs_path=users/user_123/videos/video.mp4" \ -H "X-API-Key: YOUR_API_KEY" ``` # Notify signed upload complete Source: https://docs.viddyscribe.com/api-reference/media/notify-signed-upload-complete /openapi.yaml post /enterprise/api/notify_upload_complete Signal that the client has finished uploading bytes to a signed upload URL returned by `/enterprise/api/upload_media`. This starts asynchronous verification so the media can be used for generation. # Notify signed upload complete Source: https://docs.viddyscribe.com/api-reference/media/notify-upload-complete post /enterprise/api/notify_upload_complete Signal that the client has finished uploading bytes to a signed upload URL returned by `/enterprise/api/upload_media`. This starts asynchronous verification so the media can be used for generation. ## Usage Example Call this after uploading bytes to the `upload_url` returned by `upload_media` with `input.type: "signed_url"`. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/notify_upload_complete \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "media_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_path": "users/user_123/videos/video.mp4" }' ``` # Upload media file or URL Source: https://docs.viddyscribe.com/api-reference/media/upload-media post /enterprise/api/upload_media Upload a video file directly, ingest from a URL, or request a signed upload URL for larger local files. Returns a media_id that can be used for video generation. ## Usage Examples ### 1. Upload from URL Ingest a video from a public URL. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" } }' ``` ### 2. Upload Local File Upload a video file directly. For local files up to 32 MB, multipart upload is supported directly. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \ -H "X-API-Key: YOUR_API_KEY" \ -F 'input={"type": "file"}' \ -F "file=@/path/to/video.mp4" ``` ### 3. Request a Signed Upload URL For larger local files, request a signed upload URL first. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "signed_url", "filename": "video.mp4", "content_type": "video/mp4" } }' ``` Then upload the file to `upload_url`, call `notify_upload_complete`, and poll `get_upload_status` until the upload is ready before generating with `media_id`. See [Large Local File Upload](/large-local-file-upload) for the full workflow. ## Common Upload Errors | Error | HTTP Status | Description | | ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------- | | `no_video_stream` | `415` | The uploaded file is not a valid video stream for processing. This usually means the file contains audio only. | | `video_too_long` | `403` | The uploaded video exceeds the maximum duration allowed by the current plan. | | `file_too_large` | `403` | The uploaded file exceeds the maximum file size allowed by the current plan. | Example response: ```json theme={null} { "error": "no_video_stream", "message": "The uploaded file contains audio only. Please upload a video file with at least one video stream." } ``` # Upload media file or URL Source: https://docs.viddyscribe.com/api-reference/media/upload-media-file-or-url /openapi.yaml post /enterprise/api/upload_media Upload a video file directly, ingest from a URL, or request a signed upload URL for larger local files. Returns a media_id that can be used for video generation. # API Reference Source: https://docs.viddyscribe.com/api-reference/overview Complete reference for ViddyScribe Enterprise API ## Base URL ``` https://api.viddyscribe.com ``` ## Authentication All API requests require an API key passed in the `X-API-Key` header. ```bash theme={null} X-API-Key: vsk_your_api_key_here ``` ## Endpoints ### Upload Endpoints Upload by file, URL, or request a signed upload URL Start verification after a signed upload finishes Poll signed-upload verification status ### Text Generation Endpoints Generate text using a media\_id, URL, or direct file upload ### Audio Generation Endpoints Generate an audio track using a media\_id, URL, or direct file upload ### Video Generation Endpoints Generate a video using a media\_id, URL, or direct file upload ### Results Endpoint Poll for job results and download outputs ## Quick Example ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@video.mp4" ``` ```bash theme={null} 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"}' ``` ```bash theme={null} 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](/api-reference/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` 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](/api-reference/processing/generate-audio-description-audio) additionally returns a WAV track and the [video endpoint](/api-reference/processing/generate-audio-description-video) additionally returns an MP4. For text-only output, see the [text endpoint](/api-reference/processing/generate-audio-description-text). ## 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. ```json theme={null} { "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. | | `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. | | `no_video_stream` | Upload verification found no video track in the file, usually an audio file with a video extension. Upload a file that contains video. | | `upload_failed` | Upload verification failed and the job could not be started. Re-upload the media and submit a new job. | | `file_too_large` | The uploaded file exceeds the maximum file size allowed by the plan. | | `video_too_long` | The uploaded video exceeds the maximum duration allowed by the plan. | | `video_file_missing` | The source file is no longer in storage. Upload the media again and start a new job. | | `resolution_too_high` | The source is larger than 4K. Export at 4K (2160p) or below and upload again. | 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: ```json theme={null} { "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? Email our team View usage # Generate AD audio Source: https://docs.viddyscribe.com/api-reference/processing/generate-ad-audio /openapi.yaml post /enterprise/api/generate_ad_audio Generate an audio-only track with Audio Descriptions. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. # Generate AD text Source: https://docs.viddyscribe.com/api-reference/processing/generate-ad-text /openapi.yaml post /enterprise/api/generate_ad_text Generate Audio Description text (VTT, JSON, etc.) for a video. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. # Generate AD video Source: https://docs.viddyscribe.com/api-reference/processing/generate-ad-video /openapi.yaml post /enterprise/api/generate_ad_video Generate a video with burned-in Audio Descriptions. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. # Generate AD Audio Source: https://docs.viddyscribe.com/api-reference/processing/generate-audio-description-audio post /enterprise/api/generate_ad_audio Generate an audio-only track with Audio Descriptions. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. This endpoint is available for **Standard AD only**. Descriptions are placed in existing dialogue gaps without changing the runtime. See [Standard AD vs Extended AD](/standard-vs-extended-ad) if you need pauses inserted for fuller descriptions. Extended AD is supported on the video and text endpoints. ## Usage Examples ### 1. Using an existing Media ID If you have already uploaded media and have a `media_id`, use this method. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_audio \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "media_id", "media_id": "550e8400-e29b-41d4-a716-446655440000" }, "generation_config": { "language": "en-US" } }' ``` ### 2. Using a Public URL Upload from a URL and generate in a single step. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_audio \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US" } }' ``` ### 3. Uploading a Local File Upload a file directly and generate in a single step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_audio \ -H "X-API-Key: YOUR_API_KEY" \ -F 'input={"type": "file"}' \ -F "file=@/path/to/video.mp4" \ -F 'generation_config={"language": "en-US"}' ``` ## Generation Config Options | Option | Type | Description | | ------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_fit` | boolean | Fits descriptions into detected no-speech zones when possible. | | `allow_descriptions_over_music` | boolean | Allows descriptions over detected music when no better timing is available. | | `custom_captions` | object | Uses provided captions for transcript/context instead of auto-generating them. Send `{ "content": "" }`; `format` and `filename` are optional hints. The server parses, validates, and normalizes the cues automatically. | | `volume_option` | `auto` or `max` | Use `max` to set a target max peak level for the AD track, or `auto` for the default. | | `volume_level_db` | number | Max peak level in dBFS when `volume_option` is `max`. Supported range is `-10` to `0`. | | `audio_track_type` | `mixed` or `ad_only` | Which audio track is returned as `audio_signed_url`. `mixed` (default) is the source dialogue plus AD narration. `ad_only` is just the narration WAV. | ## Troubleshooting For the full list of API error codes, see [Error Codes](/api-reference/overview#error-codes). | Error | HTTP Status | Description | | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `upload_not_ready` | `409` | Returned in the `code` field when the referenced media is still being verified after upload. Retry shortly. | | `upload_failed` | `409` | Returned in the `code` field when the referenced media failed upload verification. Re-upload the video and try again. | | `concurrency_limit_exceeded` | `429` | Too many concurrent submissions are being validated for the current team. Retry after a short delay. | # Generate AD Text Source: https://docs.viddyscribe.com/api-reference/processing/generate-audio-description-text post /enterprise/api/generate_ad_text Generate Audio Description text (VTT, JSON, etc.) for a video. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. ## Usage Examples ### 1. Using an existing Media ID If you have already uploaded media and have a `media_id`, use this method. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "media_id", "media_id": "550e8400-e29b-41d4-a716-446655440000" }, "generation_config": { "language": "en-US", "format": "vtt", "ad_type": "extended_ad" } }' ``` ### 2. Using a Public URL Upload from a URL and generate in a single step. ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US", "format": "json", "ad_type": "extended_ad" } }' ``` ### 3. Uploading a Local File Upload a file directly and generate in a single step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: YOUR_API_KEY" \ -F 'input={"type": "file"}' \ -F "file=@/path/to/video.mp4" \ -F 'generation_config={"language": "en-US", "format": "srt"}' ``` ## Generation Config Options | Option | Type | Description | | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_fit` | boolean | Fits descriptions into detected no-speech zones when possible. | | `allow_descriptions_over_music` | boolean | Allows descriptions over detected music when no better timing is available. | | `custom_captions` | object | Uses provided captions for transcript/context instead of auto-generating them. Send `{ "content": "" }`; `format` and `filename` are optional hints. The server parses, validates, and normalizes the cues automatically. | ## Troubleshooting For the full list of API error codes, see [Error Codes](/api-reference/overview#error-codes). | Error | HTTP Status | Description | | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `upload_not_ready` | `409` | Returned in the `code` field when the referenced media is still being verified after upload. Retry shortly. | | `upload_failed` | `409` | Returned in the `code` field when the referenced media failed upload verification. Re-upload the video and try again. | | `concurrency_limit_exceeded` | `429` | Too many concurrent submissions are being validated for the current team. Retry after a short delay. | # Generate AD Video Source: https://docs.viddyscribe.com/api-reference/processing/generate-audio-description-video post /enterprise/api/generate_ad_video Generate a video with burned-in Audio Descriptions. Supports Input via `media_id`, `url`, or direct `file` upload. Returns a job_id for tracking progress. ## Usage Examples ### 1. Using an existing Media ID If you have already uploaded media and have a `media_id`, use this method. ```bash theme={null} 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 '{ "input": { "type": "media_id", "media_id": "550e8400-e29b-41d4-a716-446655440000" }, "generation_config": { "language": "en-US", "format": "vtt" } }' ``` ### 2. Using a Public URL Upload from a URL and generate in a single step. ```bash theme={null} 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 '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US", "format": "vtt", "ad_type": "extended_ad" } }' ``` ### 3. Uploading a Local File Upload a file directly and generate in a single step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_video \ -H "X-API-Key: YOUR_API_KEY" \ -F 'input={"type": "file"}' \ -F "file=@/path/to/video.mp4" \ -F 'generation_config={"language": "en-US", "format": "vtt"}' ``` ## Generation Config Options | Option | Type | Description | | ------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_fit` | boolean | Fits descriptions into detected no-speech zones when possible. | | `allow_descriptions_over_music` | boolean | Allows descriptions over detected music when no better timing is available. | | `custom_captions` | object | Uses provided captions for transcript/context instead of auto-generating them. Send `{ "content": "" }`; `format` and `filename` are optional hints. The server parses, validates, and normalizes the cues automatically. | | `volume_option` | `auto` or `max` | Use `max` to set a target max peak level for the AD track, or `auto` for the default. | | `volume_level_db` | number | Max peak level in dBFS when `volume_option` is `max`. Supported range is `-10` to `0`. | ## Troubleshooting For the full list of API error codes, see [Error Codes](/api-reference/overview#error-codes). | Error | HTTP Status | Description | | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `upload_not_ready` | `409` | Returned in the `code` field when the referenced media is still being verified after upload. Retry shortly. | | `upload_failed` | `409` | Returned in the `code` field when the referenced media failed upload verification. Re-upload the video and try again. | | `concurrency_limit_exceeded` | `429` | Too many concurrent submissions are being validated for the current team. Retry after a short delay. | # Delete a generation job Source: https://docs.viddyscribe.com/api-reference/results/delete-a-generation-job /openapi.yaml delete /enterprise/api/jobs/{job_id} Delete a completed generation job created via the API. This hides the job and removes output artifacts. The job row is preserved by default. In-progress or failed jobs cannot be deleted via this endpoint. # Get job results Source: https://docs.viddyscribe.com/api-reference/results/get-job-results get /enterprise/api/get_results Check the status of a processing job and retrieve results when complete. **Job statuses:** - `queued` - Job is waiting to be processed - `processing` - Job is currently being processed - `done` - Job finished successfully - `video_signed_url`: Signed URL to download result (video/audio jobs, expires in 15 min) - `audio_signed_url`: Signed URL to download audio track (standard_ad video jobs only) - `output`: JSON/Text with generated descriptions (if available) - `failed` - Job failed, error message available # Languages and Voices Source: https://docs.viddyscribe.com/api-reference/voices Supported `language` and `voice` values for `generation_config`. ## Supported Languages Pass any of these BCP-47 codes as the `language` field in `generation_config`. Default is `en-US`. | Code | Language | | -------- | ------------------------ | | `en-US` | English (US) | | `en-GB` | English (UK) | | `en-AU` | English (Australia) | | `en-IN` | English (India) | | `es-US` | Spanish (US) | | `es-ES` | Spanish (Spain) | | `fr-FR` | French (France) | | `fr-CA` | French (Canada) | | `de-DE` | German | | `it-IT` | Italian | | `pt-BR` | Portuguese (Brazil) | | `pt-PT` | Portuguese (Portugal) | | `nl-NL` | Dutch | | `nl-BE` | Dutch (Belgium) | | `pl-PL` | Polish | | `ru-RU` | Russian | | `tr-TR` | Turkish | | `uk-UA` | Ukrainian | | `bg-BG` | Bulgarian | | `hr-HR` | Croatian | | `cs-CZ` | Czech | | `et-EE` | Estonian | | `el-GR` | Greek | | `hu-HU` | Hungarian | | `lv-LV` | Latvian | | `lt-LT` | Lithuanian | | `ro-RO` | Romanian | | `sr-RS` | Serbian (Cyrillic) | | `sk-SK` | Slovak | | `sl-SI` | Slovenian | | `da-DK` | Danish | | `fi-FI` | Finnish | | `nb-NO` | Norwegian | | `sv-SE` | Swedish | | `he-IL` | Hebrew | | `ar-XA` | Arabic (Modern Standard) | | `hi-IN` | Hindi | | `bn-IN` | Bengali (India) | | `gu-IN` | Gujarati (India) | | `kn-IN` | Kannada (India) | | `ml-IN` | Malayalam (India) | | `mr-IN` | Marathi (India) | | `pa-IN` | Punjabi (India) | | `ta-IN` | Tamil (India) | | `te-IN` | Telugu (India) | | `ur-IN` | Urdu (India) | | `id-ID` | Indonesian | | `ja-JP` | Japanese | | `ko-KR` | Korean | | `cmn-CN` | Mandarin Chinese | | `th-TH` | Thai | | `vi-VN` | Vietnamese | | `sw-KE` | Swahili (Kenya) | ## Supported Voices Pass any of these IDs as the `voice` field in `generation_config` (audio and video endpoints). Default is `Achernar`. Pick a language to see the voices available for it. Most languages are supported by all 30 Chirp voices, plus a single English-only `Robotic` voice. To preview each voice, open the [dashboard](https://viddyscribe.com/dashboard) and use the voice picker, every option has an inline play button. # Authentication Source: https://docs.viddyscribe.com/authentication Learn how to authenticate your API requests ## 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 [Contact our team](https://viddyscribe.com/pricing#contactus) to obtain an API plan and 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. The example below polls `/get_results` for a job — the same `X-API-Key` header works on every other endpoint (`/upload_media`, `/generate_ad_text`, `/generate_ad_audio`, `/generate_ad_video`, etc.): ```bash cURL theme={null} curl -X GET https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_123 \ -H "X-API-Key: vsk_your_api_key_here" ``` ```python Python theme={null} import requests headers = { "X-API-Key": "vsk_your_api_key_here" } response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_results", headers=headers, params={"job_id": "task_123"} ) ``` ```javascript JavaScript theme={null} const response = await fetch( 'https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_123', { headers: { 'X-API-Key': 'vsk_your_api_key_here' } } ); ``` ```go Go theme={null} client := &http.Client{} req, _ := http.NewRequest("GET", "https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_123", nil) req.Header.Add("X-API-Key", "vsk_your_api_key_here") resp, _ := client.Do(req) ``` ## Authentication Errors A missing or invalid API key returns `401 Unauthorized` with `error: "unauthorized"`. For the full list of error codes (auth, plan limits, rate limits, upload state, job failures), see [API Reference > Error Codes](/api-reference/overview#error-codes). ## 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. # Generate Your First Description Source: https://docs.viddyscribe.com/dashboard/generate-first-description Step-by-step guide to creating your first audio-described video in the ViddyScribe dashboard With your ViddyScribe Enterprise workspace set up, it's time to create your first audio-described video. ViddyScribe's AI engine does the heavy lifting, analyzing your video and generating natural-sounding descriptions. ## Step 1: Upload Your Video Start by navigating to the **Studio** tab in your dashboard and clicking the **Upload Videos** button. You can upload a video file directly from your computer. Alternatively, you can add videos that have already been uploaded with the **Add from Library** button, or add a link to a supported external video source with the **Add from URL** button. Note that in order to use the **Add from URL** function, external links must be publicly accessible, and point directly to the video itself, e.g. `/filename.mp4`. Pasting a link to a page where the video is hosted, such as a YouTube link, will not load videos into ViddyScribe. ViddyScribe Enterprise Studio upload screen with a Drop your videos here area and Upload Videos, Add from Library, and Add from URL buttons ## Step 2: Choose Your Audio Description Type ViddyScribe Enterprise offers two types of audio description to ensure compliance with WCAG and ADA standards. It's crucial to select the right one for your content: * **Standard AD:** This type inserts descriptions *only* into the natural pauses in the video's original audio track. It does not alter the length of the video. This is ideal when your video already has sufficient quiet moments to fit the descriptions. * **Extended AD:** If your video has continuous dialogue or fast-paced action with very few pauses, Extended AD is the solution. ViddyScribe will temporarily pause the video visually while the description plays, ensuring no critical visual information is missed by the visually impaired viewer. Generate settings for gov.mp4 with the Description Type control highlighted, offering Extended AD and Standard AD, beside a preview of a city council video ## Step 3: Select Your Workflow Mode Choose whether you want ViddyScribe to automatically generate your AD script, convert it to speech, and encode it into your video (**Auto**) or if you want it to only generate the AD script, so that you can make edits to it before converting the script to speech and encoding it into your video (**Text Only**). Generate settings with the Mode control highlighted, showing Auto (Default) selected and Text Only as the alternative, with the note Generates AD Video + AD Text + CC Text ## Step 4: Select Language and Video Category ViddyScribe supports multiple languages and dialects. If the language or dialect you need is not available, email `support@viddyscribe.com` to make a request. Note that not all languages or dialects can be accommodated. Generate settings with the Language and Video Category dropdowns highlighted, set to English (US) and Auto-detect ## Step 5: Give ViddyScribe Additional Instructions (Optional) These settings fine-tune ViddyScribe's initial output and tailor them with proper context for your viewers. * In the **Additional Instructions** field, add up to 2000 characters to tell ViddyScribe how to describe your video. This can be useful for subject/character names, description tone, or a custom glossary of terms. Generate settings with the Additional Instructions text box highlighted, showing a 0 of 500 character count and example placeholder text ## Step 6: Closed Captions If you have your own closed captions file, you can upload them to ViddyScribe so that it will incorporate them with your generated outputs. If you don't have your own closed captions file, leave **Auto-generate Captions** checked. Closed Captions section highlighted in the Generate settings, with Upload Your Own selected and an Upload .srt or .vtt button below the Auto Generate (Default) option ## Step 7: Select Voice and Peaking Level These options are available if you have selected the **Auto** workflow mode. * Listen to the voice previews and select the one that best fits the tone and style of your content. * Manually choose your desired peaking level for generated speech. * If you have selected **Text Only**, you will select your voice and peaking level in the Edit tab instead of the Generate tab. See [Editing in the Timeline](/dashboard/timeline-editor) for the full editing workflow. Audio section highlighted in the Generate settings, with the Voice dropdown set to Achernar (Female) and Audio Level for Descriptions set to Set Peak Level at -6 dB ## Step 8: Generate Once you've configured your settings, click **Generate**. ViddyScribe will now process your video. The processing time depends on the length of your video, but you can navigate away from the page while it works. Your output will appear at the top of your Library when it is complete. ## Step 9: Download Your Accessible Video Outputs Unlike Individual plans where users can only share links, ViddyScribe Enterprise gives you full control over your assets. Once processing is complete, head over to **Library** to download your files in several formats: * **Burned-in Video (MP4):** A new video file with the audio description track permanently mixed in. * **Audio Track Only (WAV):** Standard AD outputs will optionally provide the isolated audio description track, which is useful if you are mixing it yourself in an external video editor or sideloading it into an existing video on a platform like YouTube. * **Description, Caption, and Transcript (VTT, TXT, JSON, and more):** A text transcript of the descriptions with timestamps. ViddyScribe Library page with a table of completed generations and a detail panel for gov (5).mp4 showing the output video, with the download button and VTT description transcript highlighted Need to make a few tweaks before exporting? No problem. Our next guide covers how to use the Edit tab to perfect your descriptions. **Next:** [Editing in the Timeline](/dashboard/timeline-editor) # Editing in the Timeline Source: https://docs.viddyscribe.com/dashboard/timeline-editor Refine generated audio descriptions with the Edit tab, Timeline Editor, and Smart Edit ViddyScribe's AI engine creates excellent audio descriptions right out of the box. But sometimes, you need absolute control over the phrasing, timing, or length of a description to meet specific accessibility standards or artistic intent. ViddyScribe Enterprise provides powerful tools for refining your content. In this guide, we'll explore how to use the **Edit Tab**, specifically the **Timeline Editor** and the AI-powered **Smart Edit** feature. ## Step 1: Accessing the Edit Tab After ViddyScribe has finished generating descriptions for your video (whether you chose the Auto or Text Only workflow): 1. Go to the **Library** section of your dashboard. 2. Click on the video you want to review. 3. Select the **Magic Wand** icon to open the Edit tab of the Studio workspace, where you can see all generated descriptions alongside the video preview. ViddyScribe Library page with Library highlighted in the sidebar and the Magic Wand icon highlighted in the detail panel for gov (5).mp4, showing a Load Descriptions in Studio tooltip ## Step 2: Editing the Text Need to change a word, rephrase a sentence, or adjust descriptions from a generation? * In the Edit tab, you'll see a list of all descriptions. * Click on the text of any description to modify it manually. * Select your preferred voice and peaking level here before generating the final audio. * The TTS engine will automatically update to reflect your new text. Studio Edit tab for gov (5).mp4 with the Custom Descriptions text box highlighted, showing numbered WEBVTT description cues with timestamps, and the numbered description markers under the video preview also highlighted Studio Edit tab with the Audio section highlighted, showing the Voice dropdown set to Achernar (Female) and Audio Level for Descriptions set to Set Peak Level at -6 dB ## Step 3: Using the Timeline Editor The Timeline Editor is a visual, drag-and-drop interface that makes it easy to adjust exactly when a description plays. * **Moving a Description:** Simply click and drag a description block along the timeline to change its start time. * **Move to Playhead:** Select a description block by clicking on it and click the **Move to Playhead** button to move the description to the same position as the playhead. * **Add New Descriptions:** Use the **Add New Description** button to insert a new description manually at the playhead's position. * **Zoom In and Out:** Use the **Zoom** controls to get a more complete look at your timeline, or to zero in on the exact frame you want your description to occur. Studio Edit tab with the Open Editor button highlighted below the video preview and its numbered description markers Full-screen Timeline Editor with a city council video preview, a Move to playhead button, a zoom slider, two description blocks on the timeline with their start and end times, and the WEBVTT description list with an Add Description button on the right ## Step 4: Using AI-Powered Smart Edit Smart Edit is a powerful feature that lets you use natural language to modify your descriptions, saving you time and effort. 1. In the Edit tab, open the **Smart Edit** input field by clicking the **magic wand** icon. 2. Type a natural language instruction. For example: * *"Shorten all descriptions to 8 words or less."* * *"Make all of the descriptions more impactful and punchier."* * *"Change all references to 'the man' to 'John'."* * *"Translate all descriptions to Spanish."* * *"Move all timestamps forward by 2 seconds."* 3. Click **Apply AI Edit**. ViddyScribe's AI will interpret your instructions, adjust the text or timestamps accordingly, and present the changes for your review, saving you minutes to hours in your revision process. Two stacked screenshots: the sparkle Smart Edit icon highlighted above the description list in the editor, and the Smart Edit Descriptions dialog with an instructions text box and Cancel and Apply AI Edit buttons ## Step 5: Generate Edited Video Once you are satisfied with your edits: * Click **Edit Video with Descriptions** to finalize the video with your selected voice and peaking level. * You can then proceed to the **Library** to download your final audio described video (MP4), audio track (WAV), or text file (VTT/TXT/JSON). Studio Edit tab with the Edit Video with Descriptions button highlighted at the bottom of the settings panel, below the Custom Descriptions text box # Generate AD Audio Source: https://docs.viddyscribe.com/generate-ad-audio Quick guide to generate audio description audio track via URL ## Generate AD Audio Generate an audio-only track with audio descriptions (no video rendering). This is useful when you only need the audio track without video processing. Already uploaded media or using the signed upload flow? Generate with `media_id`. See [Large Local File Upload](/large-local-file-upload) or [API Reference](/api-reference/processing/generate-audio-description-audio). ### 1. Using a Video from public URL Upload from a public URL and generate in one step. ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_audio \ -H "X-API-Key: vsk_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US", "voice": "Achernar", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text." } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_audio", headers={"X-API-Key": "vsk_your_api_key_here"}, json={ "input": {"type": "url", "url": "https://example.com/video.mp4"}, "generation_config": { "language": "en-US", "voice": "Achernar", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }, }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_audio", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here", "Content-Type": "application/json", }, body: JSON.stringify({ input: { type: "url", url: "https://example.com/video.mp4" }, generation_config: { language: "en-US", voice: "Achernar", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", }, }), } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Use the `job_id` to poll `get_results` for completion. ### 2. Using a Video from local file Upload a local file and generate in one step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_audio \ -H "X-API-Key: vsk_your_api_key_here" \ -F 'input={"type": "file"}' \ -F "file=@video.mp4" \ -F 'generation_config={"language": "en-US", "voice": "Achernar", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text."}' ``` ```python Python theme={null} import json import requests with open("video.mp4", "rb") as f: response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_audio", headers={"X-API-Key": "vsk_your_api_key_here"}, files={"file": f}, data={ "input": json.dumps({"type": "file"}), "generation_config": json.dumps({ "language": "en-US", "voice": "Achernar", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }), }, ) print(response.json()) ``` ```javascript JavaScript theme={null} import fs from "node:fs"; const form = new FormData(); form.append("input", JSON.stringify({ type: "file" })); form.append("file", new Blob([fs.readFileSync("video.mp4")]), "video.mp4"); form.append("generation_config", JSON.stringify({ language: "en-US", voice: "Achernar", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", })); const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_audio", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here" }, body: form, } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "660f9511-f30c-52e5-b827-557766551111" } ``` Use the `job_id` to poll `get_results` for completion. On success, `audio_signed_url` contains a signed URL to download the audio track (WAV format). ## Tips * **Note:** Audio generation only supports `standard_ad` type (concise descriptions during dialogue pauses). * The default text output `format` is `json`. Set `format` to `"vtt"` to include a WebVTT string in the response `output`. * Audio output is priced at 0.75x the base workflow cost. * Use `custom_instructions` to guide the AI's description style (e.g. tone, focus, or length). * Set `audio_track_type` to `"ad_only"` to receive just the AD narration WAV; the default `"mixed"` returns the source dialogue plus AD narration. ## Retrieve Results Use the `job_id` from the previous step to fetch results: ```bash cURL theme={null} curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID" \ -H "X-API-Key: vsk_your_api_key_here" ``` ```python Python theme={null} import requests response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_results", headers={"X-API-Key": "vsk_your_api_key_here"}, params={"job_id": "TASK_ID"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID", { headers: { "X-API-Key": "vsk_your_api_key_here" } } ); console.log(await response.json()); ``` Example successful response for audio jobs (with `format: "vtt"`): ```json theme={null} { "job_id": "task_abc123xyz", "status": "done", "media_id": "550e8400-e29b-41d4-a716-446655440000", "audio_signed_url": "https://storage.googleapis.com/bucket/path/to/audio.wav?X-Goog-Signature=...", "output": { "format": "vtt", "content": "WEBVTT\n\n1\n00:00:00.500 --> 00:00:03.100\nA woman in a yellow top sits at a desk with a laptop.\n\n2\n00:00:03.200 --> 00:00:05.900\nShe looks at the camera and smiles.\n" }, "created_at": "2025-09-30T08:00:00Z", "updated_at": "2025-09-30T08:10:00Z" } ``` # Generate AD Text Source: https://docs.viddyscribe.com/generate-ad-text Quick guide to generate audio description text via URL or local file ## Generate AD Text Pick one of the two simple flows below to generate audio description text. Already uploaded media or using the signed upload flow? Generate with `media_id`. See [Large Local File Upload](/large-local-file-upload) or [API Reference](/api-reference/processing/generate-audio-description-text). ### 1. Using a Video from public URL Upload from a public URL and generate in one step. ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: vsk_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text." } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", headers={"X-API-Key": "vsk_your_api_key_here"}, json={ "input": {"type": "url", "url": "https://example.com/video.mp4"}, "generation_config": { "language": "en-US", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }, }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here", "Content-Type": "application/json", }, body: JSON.stringify({ input: { type: "url", url: "https://example.com/video.mp4" }, generation_config: { language: "en-US", ad_type: "extended_ad", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", }, }), } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Use the `job_id` to poll `get_results` for completion. ### 2. Using a Video from local file Upload a local file and generate in one step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: vsk_your_api_key_here" \ -F 'input={"type": "file"}' \ -F "file=@video.mp4" \ -F 'generation_config={"language": "en-US", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text."}' ``` ```python Python theme={null} import json import requests with open("video.mp4", "rb") as f: response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", headers={"X-API-Key": "vsk_your_api_key_here"}, files={"file": f}, data={ "input": json.dumps({"type": "file"}), "generation_config": json.dumps({ "language": "en-US", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }), }, ) print(response.json()) ``` ```javascript JavaScript theme={null} import fs from "node:fs"; const form = new FormData(); form.append("input", JSON.stringify({ type: "file" })); form.append("file", new Blob([fs.readFileSync("video.mp4")]), "video.mp4"); form.append("generation_config", JSON.stringify({ language: "en-US", ad_type: "extended_ad", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", })); const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here" }, body: form, } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "660f9511-f30c-52e5-b827-557766551111" } ``` Use the `job_id` to poll `get_results` for completion. On success, `output.content` contains the VTT string (or `output.segments` for JSON format). ## Tips * The default text output `format` is `json`. Set `format` to `"vtt"` to include a WebVTT string in the response `output`. * Choose `standard_ad` or `extended_ad` based on your timing and detail needs. See [Standard AD vs Extended AD](/standard-vs-extended-ad). * Use `custom_instructions` to guide the AI's description style (e.g. tone, focus, or length). * Set `read_all_onscreen_text: true` for educational, government, or news content to force the AI to read slides, lower thirds, and on-screen labels verbatim (only applies when `ad_type` is `extended_ad`). ## Retrieve Results Use the `job_id` from the previous step to fetch results: ```bash cURL theme={null} curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID" \ -H "X-API-Key: vsk_your_api_key_here" ``` ```python Python theme={null} import requests response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_results", headers={"X-API-Key": "vsk_your_api_key_here"}, params={"job_id": "TASK_ID"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID", { headers: { "X-API-Key": "vsk_your_api_key_here" } } ); console.log(await response.json()); ``` Example successful response for text jobs (with `format: "vtt"`): ```json theme={null} { "job_id": "task_abc123xyz", "status": "done", "media_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2025-09-30T08:00:00Z", "updated_at": "2025-09-30T08:10:00Z", "output": { "format": "vtt", "content": "WEBVTT\n\n1\n00:00:00.500 --> 00:00:03.100\nA woman in a yellow top sits at a desk with a laptop.\n\n2\n00:00:03.200 --> 00:00:05.900\nShe looks at the camera and smiles.\n" } } ``` Example successful response for text jobs (with `format: "json"`): ```json theme={null} { "job_id": "task_abc123xyz", "status": "done", "media_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2025-09-30T08:00:00Z", "updated_at": "2025-09-30T08:10:00Z", "output": { "format": "json", "segments": [ { "id": "1", "start_time": 0.500, "end_time": 3.100, "description": "A woman in a yellow top sits at a desk with a laptop." }, { "id": "2", "start_time": 3.200, "end_time": 5.900, "description": "She looks at the camera and smiles." } ] } } ``` # Generate AD Video Source: https://docs.viddyscribe.com/generate-ad-video Quick guide to generate audio description video via URL or local file ## Generate AD Video Pick one of the two simple flows below to generate audio description video. Already uploaded media or using the signed upload flow? Generate with `media_id`. See [Large Local File Upload](/large-local-file-upload) or [API Reference](/api-reference/processing/generate-audio-description-video). ### 1. Using a Video from public URL Upload from a public URL and generate in one step. ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_video \ -H "X-API-Key: vsk_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "url", "url": "https://example.com/video.mp4" }, "generation_config": { "language": "en-US", "voice": "Achernar", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text." } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_video", headers={"X-API-Key": "vsk_your_api_key_here"}, json={ "input": {"type": "url", "url": "https://example.com/video.mp4"}, "generation_config": { "language": "en-US", "voice": "Achernar", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }, }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_video", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here", "Content-Type": "application/json", }, body: JSON.stringify({ input: { type: "url", url: "https://example.com/video.mp4" }, generation_config: { language: "en-US", voice: "Achernar", ad_type: "extended_ad", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", }, }), } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Use the `job_id` to poll `get_results` for completion. ### 2. Using a Video from local file Upload a local file and generate in one step. Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload). ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_video \ -H "X-API-Key: vsk_your_api_key_here" \ -F 'input={"type": "file"}' \ -F "file=@video.mp4" \ -F 'generation_config={"language": "en-US", "voice": "Achernar", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text."}' ``` ```python Python theme={null} import json import requests with open("video.mp4", "rb") as f: response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_video", headers={"X-API-Key": "vsk_your_api_key_here"}, files={"file": f}, data={ "input": json.dumps({"type": "file"}), "generation_config": json.dumps({ "language": "en-US", "voice": "Achernar", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text.", }), }, ) print(response.json()) ``` ```javascript JavaScript theme={null} import fs from "node:fs"; const form = new FormData(); form.append("input", JSON.stringify({ type: "file" })); form.append("file", new Blob([fs.readFileSync("video.mp4")]), "video.mp4"); form.append("generation_config", JSON.stringify({ language: "en-US", voice: "Achernar", ad_type: "extended_ad", format: "vtt", custom_instructions: "Keep descriptions concise and focus on on-screen text.", })); const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_video", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here" }, body: form, } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "660f9511-f30c-52e5-b827-557766551111" } ``` Use the `job_id` to poll `get_results` for completion. On success, `video_signed_url` contains the link to the generated video. ## Tips * The default output `format` is `vtt`. * Choose `standard_ad` or `extended_ad` based on your timing and detail needs. See [Standard AD vs Extended AD](/standard-vs-extended-ad). * Use `custom_instructions` to guide the AI's description style (e.g. tone, focus, or length). * Set `read_all_onscreen_text: true` for educational, government, or news content to force the AI to read slides, lower thirds, and on-screen labels verbatim (only applies when `ad_type` is `extended_ad`). ## Retrieve Results Use the `job_id` from the previous step to fetch results: ```bash cURL theme={null} curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID" \ -H "X-API-Key: vsk_your_api_key_here" ``` ```python Python theme={null} import requests response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_results", headers={"X-API-Key": "vsk_your_api_key_here"}, params={"job_id": "TASK_ID"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID", { headers: { "X-API-Key": "vsk_your_api_key_here" } } ); console.log(await response.json()); ``` Example successful response for video jobs (with `format: "vtt"`): ```json theme={null} { "job_id": "task_abc123xyz", "status": "done", "media_id": "550e8400-e29b-41d4-a716-446655440000", "video_signed_url": "https://storage.googleapis.com/bucket/path/to/video.mp4?X-Goog-Signature=...", "output": { "format": "vtt", "content": "WEBVTT\n\n1\n00:00:00.500 --> 00:00:03.100\nA woman in a yellow top sits at a desk with a laptop.\n\n2\n00:00:03.200 --> 00:00:05.900\nShe looks at the camera and smiles.\n" }, "created_at": "2025-09-30T08:00:00Z", "updated_at": "2025-09-30T08:10:00Z" } ``` # Contact & Support Source: https://docs.viddyscribe.com/help/contact How to get help quickly ## Contact & Support * Email: `hello@viddyscribe.com` * Dashboard: [https://viddyscribe.com/dashboard](https://viddyscribe.com/dashboard) * Bug reports: include request ID, timestamp, and endpoint. # Credits & Usage Source: https://docs.viddyscribe.com/help/credits-and-usage How credits are counted, what different generations cost, and what happens when you run out ViddyScribe Enterprise uses **credits** to measure your usage. This page explains how credits are counted, what each type of generation costs, and what happens when your balance runs low. ## What is a credit? **One credit equals one minute of source video.** Your usage is based on the duration of the video you upload, not the length of the generated audio description or output video. From 1 October 2026, free individual accounts with no team pay whole credits: each video is rounded up to the next whole minute, with a minimum of one credit. A 2.3-minute video uses 3 credits. Videos generated before that date keep the earlier tenth-of-a-credit rounding. Paid plans and team plans count usage to a tenth of a credit. ## How cost is calculated Different workflows consume credits at different rates, based on your source video's duration: | Generation type | Credit cost | | ------------------------------------------------------------------------- | -------------------- | | Generate AD video (includes text, audio, and the burned-in video) | 1× video duration | | Generate AD audio, Standard AD only (includes text and the audio track) | 0.75× video duration | | Generate AD text only | 0.5× video duration | | Generate AD video from existing text (re-uses text you already generated) | 0.5× video duration | \* Custom Enterprise plans may have different rates. Contact us for details on your plan. ### Closed captions and transcripts Closed captions and a transcript are produced as part of any generation you run from the dashboard, at **no extra credit cost**. They are included in the rates above rather than billed separately. Generations run through the **API do not include** captions or transcripts. ## Shared across your team Credits are **pooled at the team level**. All members share the same balance, and every generation counts toward that shared pool regardless of who ran it. ## Monthly vs. Annual plans Enterprise plans come in two billing cadences: * **Monthly:** credits refresh each month and unused credits do not roll over. * **Annual:** credits refresh each year, unused credits roll over for the duration of the plan, and annual billing is discounted versus monthly. See [our pricing page](https://viddyscribe.com/pricing) for available plans, or [request a custom plan](https://viddyscribe.com/pricing#contactus) for additional capacity. ## What happens when credits run out When your team's balance reaches zero, **new generations are blocked**. Jobs that are still processing also **reserve their estimated cost** until they finish. Those reserved minutes are not available for a new job, even if the dashboard still shows them as remaining. A job can therefore be refused for insufficient credits while another video is still processing. To avoid interruptions: * **Upgrade your plan**. * **Purchase additional credits** as a top-up. Top-ups expire at the end of your current billing cycle. Monthly plans lose unused top-up credits at the next monthly reset, while annual plans roll unused top-ups over for as long as the annual plan remains active. Use your [dashboard plan page](https://viddyscribe.com/dashboard/plan) to upgrade or add credits. ## Other notes * **Re-runs cost credits.** Regenerating text, audio, or video counts as a new job. * **AI Smart Edit is free.** It rewrites description text using AI without re-analyzing the video, so it doesn't consume credits. You're only charged when you re-generate audio or video from the edited text. * **Downloads and exports** are always free once a video has been generated. # FAQ Source: https://docs.viddyscribe.com/help/faq Answers to common questions about authentication, processing, and results ### Where do I find my API key? On a team with API access, an owner or admin can create a key on the dashboard's **API keys** page. Members should get a key from an owner or admin; existing key secrets cannot be displayed again. [Contact our team](https://viddyscribe.com/pricing#contactus) if your team needs API access. Keep keys on your server and out of source control. ### How long does it take to generate text? Once the video starts processing, a 10 minute video typically takes \~3-5 minutes for descriptions to be generated. Total time may be longer if you have more videos in the queue than your concurrency limits. ### How long does it take to generate audio? Once the video starts processing, a 10 minute video typically takes \~4-6 minutes for the audio track to be generated. Total time may be longer if you have more videos in the queue than your concurrency limits. ### How long does it take to generate video? Once the video starts processing, a 10 minute video typically takes \~8-12 minutes for the video to be generated. Total time may be longer if you have more videos in the queue than your concurrency limits. # Teams & Permissions Source: https://docs.viddyscribe.com/help/team-roles What Owners, Admins, Members, and Billing contacts can do in a ViddyScribe team ViddyScribe teams have four roles: **Owner**, **Admin**, **Member**, and **Billing**. Each role controls which actions a user can take on the team. ## Role permissions | Action | Owner | Admin | Member | Billing | | ----------------------------------------------- | :---: | :---: | :----: | :-----: | | View team info & members | Yes | Yes | Yes | — | | Accept invites | Yes | Yes | Yes | Yes | | Manage members *(invite, remove, change roles)* | Yes | Yes | — | — | | Manage invites *(view pending, revoke)* | Yes | Yes | — | — | | Manage API keys *(create, revoke, delete)* | Yes | Yes | — | — | | View team usage & analytics | Yes | Yes | — | — | | Manage billing and seats | Yes | Yes | — | Yes | ## Team seats All Enterprise plans include **5 working seats** at no additional cost. Active owners, admins, and members use a seat; billing contacts and pending invites do not. To add more seats, email [hello@viddyscribe.com](mailto:hello@viddyscribe.com). Additional seats start at **\$20 per seat per month** and scale with your plan. # ViddyScribe Docs Source: https://docs.viddyscribe.com/introduction Choose the guide, API reference, or support resource that matches what you want to do. Welcome to the ViddyScribe docs. Pick the path that matches what you are trying to do. Step-by-step guides for creating, reviewing, editing, and exporting audio-described videos in the ViddyScribe dashboard. Endpoint reference, request formats, response examples, voices, upload flows, and result polling. Generate your first audio description through the API in a few minutes. Find answers about credits, team roles, Standard AD vs Extended AD, and support. ## Choose Your Goal Create your first audio-described video from the web app. Refine descriptions, adjust timing, and generate edited video outputs. Learn when to use Standard AD or Extended AD. Create timestamped audio description text in VTT, SRT, JSON, or EDL. Create an audio description track from a video. Create a final video with audio descriptions included. ## API Shortcuts Learn how to use your ViddyScribe API key. Upload a video file or provide a URL. Use the signed upload flow for larger files. Review supported languages, voices, and narrator options. ## How ViddyScribe Works Upload media in the dashboard or provide a file, URL, or `media_id` through the API. Pick text, audio, or video output, then choose language, voice, format, and AD type. Download the result, poll for completion through the API, or edit the timeline in the dashboard. Not sure where to begin? Start with [Generate Your First Description](/dashboard/generate-first-description) if you are using the dashboard, or [Quickstart](/quickstart) if you are using the API. # Uploading Large Files Source: https://docs.viddyscribe.com/large-local-file-upload Upload larger local video files with the signed upload flow, then generate with media_id ## When to Use This Use this flow for local video files larger than 32 MB. Direct multipart upload is supported for smaller files, but larger local files should use the signed upload flow. Your plan's file-size limits still apply. ## Workflow ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "signed_url", "filename": "video.mp4", "content_type": "video/mp4" } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/upload_media", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "input": { "type": "signed_url", "filename": "video.mp4", "content_type": "video/mp4", } }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/upload_media", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ input: { type: "signed_url", filename: "video.mp4", content_type: "video/mp4", }, }), } ); console.log(await response.json()); ``` **Response:** ```json theme={null} { "media_id": "550e8400-e29b-41d4-a716-446655440000", "upload_url": "https://storage.googleapis.com/bucket/path/to/video.mp4?X-Goog-Signature=...", "gcs_path": "users/user_123/videos/video.mp4", "status": "pending_upload", "content_type": "video/mp4" } ``` Use the returned `upload_url` to `PUT` the file directly to storage. ```bash cURL theme={null} curl -X PUT "UPLOAD_URL" \ -H "Content-Type: video/mp4" \ --upload-file ./video.mp4 ``` ```python Python theme={null} import requests with open("video.mp4", "rb") as f: response = requests.put( "UPLOAD_URL", headers={"Content-Type": "video/mp4"}, data=f, ) response.raise_for_status() ``` ```javascript JavaScript theme={null} import fs from "node:fs"; const response = await fetch("UPLOAD_URL", { method: "PUT", headers: { "Content-Type": "video/mp4" }, body: fs.readFileSync("./video.mp4"), }); if (!response.ok) throw new Error(`Upload failed: ${response.status}`); ``` ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/notify_upload_complete \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "media_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_path": "users/user_123/videos/video.mp4" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/notify_upload_complete", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "media_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_path": "users/user_123/videos/video.mp4", }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/notify_upload_complete", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ media_id: "550e8400-e29b-41d4-a716-446655440000", gcs_path: "users/user_123/videos/video.mp4", }), } ); console.log(await response.json()); ``` ```bash cURL theme={null} curl "https://api.viddyscribe.com/enterprise/api/get_upload_status?media_id=550e8400-e29b-41d4-a716-446655440000&gcs_path=users/user_123/videos/video.mp4" \ -H "X-API-Key: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_upload_status", headers={"X-API-Key": "YOUR_API_KEY"}, params={ "media_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_path": "users/user_123/videos/video.mp4", }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const url = new URL( "https://api.viddyscribe.com/enterprise/api/get_upload_status" ); url.searchParams.set("media_id", "550e8400-e29b-41d4-a716-446655440000"); url.searchParams.set("gcs_path", "users/user_123/videos/video.mp4"); const response = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); console.log(await response.json()); ``` Wait until `upload_status` is `completed`. If `canonical_media_id` differs from the original `media_id`, use `canonical_media_id` for generation. After upload verification completes, call a text, audio, or video generation endpoint with `input.type: "media_id"`. ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "type": "media_id", "media_id": "550e8400-e29b-41d4-a716-446655440000" }, "generation_config": { "language": "en-US", "format": "json" } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "input": { "type": "media_id", "media_id": "550e8400-e29b-41d4-a716-446655440000", }, "generation_config": {"language": "en-US", "format": "json"}, }, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ input: { type: "media_id", media_id: "550e8400-e29b-41d4-a716-446655440000", }, generation_config: { language: "en-US", format: "json" }, }), } ); console.log(await response.json()); ``` ## Related Reference Pages * [Upload Media](/api-reference/media/upload-media) * [Notify Upload Complete](/api-reference/media/notify-upload-complete) * [Get Upload Status](/api-reference/media/get-upload-status) * [Generate AD Text](/api-reference/processing/generate-audio-description-text) * [Generate AD Audio](/api-reference/processing/generate-audio-description-audio) * [Generate AD Video](/api-reference/processing/generate-audio-description-video) # Quickstart Source: https://docs.viddyscribe.com/quickstart Get started with ViddyScribe API in under 5 minutes ## Quick Setup Get your first audio description video in 3 simple steps. [Contact our team](https://viddyscribe.com/pricing#contactus) to obtain an API plan and key. ```bash theme={null} X-API-Key: vsk_your_api_key_here ``` Upload your video and generate descriptions in one step: ```bash cURL theme={null} curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \ -H "X-API-Key: vsk_your_api_key_here" \ -F 'input={"type": "file"}' \ -F "file=@video.mp4" \ -F 'generation_config={"language": "en-US", "ad_type": "extended_ad", "format": "vtt"}' ``` ```python Python theme={null} import json import requests with open("video.mp4", "rb") as f: response = requests.post( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", headers={"X-API-Key": "vsk_your_api_key_here"}, files={"file": f}, data={ "input": json.dumps({"type": "file"}), "generation_config": json.dumps({ "language": "en-US", "ad_type": "extended_ad", "format": "vtt", }), }, ) print(response.json()) ``` ```javascript JavaScript theme={null} import fs from "node:fs"; const form = new FormData(); form.append("input", JSON.stringify({ type: "file" })); form.append("file", new Blob([fs.readFileSync("video.mp4")]), "video.mp4"); form.append("generation_config", JSON.stringify({ language: "en-US", ad_type: "extended_ad", format: "vtt", })); const response = await fetch( "https://api.viddyscribe.com/enterprise/api/generate_ad_text", { method: "POST", headers: { "X-API-Key": "vsk_your_api_key_here" }, body: form, } ); console.log(await response.json()); ``` You can also pass `input.type: "url"` or `input.type: "media_id"` instead of uploading a file directly — see the [generate AD text reference](/api-reference/processing/generate-audio-description-text) for the JSON variants. **Response:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "queued", "media_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Poll for completion and download: ```bash cURL theme={null} curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_abc123xyz" \ -H "X-API-Key: vsk_your_api_key_here" ``` ```python Python theme={null} import requests response = requests.get( "https://api.viddyscribe.com/enterprise/api/get_results", headers={"X-API-Key": "vsk_your_api_key_here"}, params={"job_id": "task_abc123xyz"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.viddyscribe.com/enterprise/api/get_results?job_id=task_abc123xyz", { headers: { "X-API-Key": "vsk_your_api_key_here" } } ); console.log(await response.json()); ``` **When done:** ```json theme={null} { "job_id": "task_abc123xyz", "status": "done", "media_id": "550e8400-e29b-41d4-a716-446655440000", "output": { "format": "vtt", "content": "WEBVTT\n\n1\n00:00:00.500 --> 00:00:03.100\nA woman in a yellow top sits at a desk with a laptop.\n\n2\n00:00:03.200 --> 00:00:05.900\nShe looks at the camera and smiles." } } ``` ## That's it! A 10 minute video usually takes up to 5 minutes for descriptions to be generated. ## What's Next? Explore all available endpoints Learn about API authentication Generate a standalone audio track with descriptions Generate an MP4 with descriptions mixed in # Standard AD vs Extended AD Source: https://docs.viddyscribe.com/standard-vs-extended-ad Choose the right audio description mode for your video ## Standard AD vs Extended AD ViddyScribe supports two audio description modes through the `ad_type` field: | Mode | API value | Best for | Timing behavior | | ----------- | ------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | Standard AD | `standard_ad` | Concise descriptions that fit around existing speech | Places descriptions in natural pauses and no-speech zones. | | Extended AD | `extended_ad` | Fuller descriptions when the video needs more visual context | Can extend or adjust timing to make room for longer descriptions. | ## Standard AD Use `standard_ad` when you want concise descriptions that avoid interrupting dialogue or important audio. This is usually the right choice for videos with enough natural pauses, simple scenes, or workflows that need a separate audio description track. ```json theme={null} { "generation_config": { "ad_type": "standard_ad", "auto_fit": true } } ``` Set `standard_ad_min_cue_length` to control the shortest silent gap a description may be placed in, in seconds. Gaps shorter than this are skipped instead of squeezing text in, so raise it for fewer, longer, more natural descriptions (useful for broadcast-style guidelines). The default is `0.75`, the typical range is `0.75`–`5`, and it only applies when `auto_fit` is on. ## Extended AD Use `extended_ad` when the video has dense visual information, important on-screen context, or scenes that need more detail than natural pauses allow. Extended AD is useful for educational material, tutorials, government meetings, news, and other content where missing visual details can make the video hard to follow. ```json theme={null} { "generation_config": { "ad_type": "extended_ad", "read_all_onscreen_text": true } } ``` ## Related Settings | Option | Applies to | Description | | ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `auto_fit` | Standard AD and Extended AD | Fits descriptions into detected no-speech zones when possible. | | `allow_descriptions_over_music` | Standard AD and Extended AD | Allows descriptions over detected music when no better timing is available. | | `standard_ad_min_cue_length` | Standard AD | Minimum silent-gap length, in seconds, where a description may be placed. Gaps shorter than this are skipped instead of squeezing text in. Default `0.75`; typical range `0.75`–`5`. Only applies when `auto_fit` is on. | | `read_all_onscreen_text` | Extended AD | Forces the model to read on-screen text verbatim for supported content types. |