> ## 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.

# API Reference

> 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

<CardGroup cols={3}>
  <Card title="Upload Media" icon="upload" href="/api-reference/media/upload-media">
    Upload by file, URL, or request a signed upload URL
  </Card>

  <Card title="Notify Upload Complete" icon="check" href="/api-reference/media/notify-upload-complete">
    Start verification after a signed upload finishes
  </Card>

  <Card title="Get Upload Status" icon="clock" href="/api-reference/media/get-upload-status">
    Poll signed-upload verification status
  </Card>
</CardGroup>

### Text Generation Endpoints

<CardGroup cols={1}>
  <Card title="Generate Text" icon="file-lines" href="/api-reference/processing/generate-audio-description-text">
    Generate text using a media\_id, URL, or direct file upload
  </Card>
</CardGroup>

### Audio Generation Endpoints

<CardGroup cols={1}>
  <Card title="Generate Audio" icon="volume-high" href="/api-reference/processing/generate-audio-description-audio">
    Generate an audio track using a media\_id, URL, or direct file upload
  </Card>
</CardGroup>

### Video Generation Endpoints

<CardGroup cols={1}>
  <Card title="Generate Video" icon="video" href="/api-reference/processing/generate-audio-description-video">
    Generate a video using a media\_id, URL, or direct file upload
  </Card>
</CardGroup>

### Results Endpoint

<CardGroup cols={1}>
  <Card title="Get Results" icon="download" href="/api-reference/results/get-job-results">
    Poll for job results and download outputs
  </Card>
</CardGroup>

## Quick Example

<Steps>
  <Step title="Upload">
    ```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"
    ```
  </Step>

  <Step title="Generate">
    ```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"}'
    ```
  </Step>

  <Step title="Get Results">
    ```bash theme={null}
    curl "https://api.viddyscribe.com/enterprise/api/get_results?job_id=JOB_ID" \
      -H "X-API-Key: YOUR_API_KEY"
    ```
  </Step>
</Steps>

## 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

<Accordion title="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
</Accordion>

## 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.                                                                                                                 |
| `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.                                                                                                |

<Note>
  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`.
</Note>

## 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?

<CardGroup cols={2}>
  <Card title="Support" icon="life-ring" href="mailto:hello@viddyscribe.com">
    Email our team
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://viddyscribe.com/dashboard">
    View usage
  </Card>
</CardGroup>