> ## 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. # 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. ## OpenAPI ````yaml /openapi.yaml post /enterprise/api/generate_ad_text openapi: 3.0.3 info: title: ViddyScribe Enterprise API version: 1.0.0 description: > Enterprise API for ViddyScribe video processing and audio description generation. ## Authentication All endpoints require API key authentication via the `X-API-Key` header. ## Workflow 1. Upload media using `/upload_media` - Returns `media_id` 2. Generate text with `/generate_ad_text`, video with `/generate_ad_video`, or audio with `/generate_ad_audio` - Returns `job_id` 3. Poll for results using `/get_results` - Returns status and outputs when done contact: name: ViddyScribe Support email: hello@viddyscribe.com servers: - url: https://api.viddyscribe.com description: Production server security: - ApiKeyAuth: [] tags: - name: Media description: Media upload operations - name: Processing description: Video processing operations - name: Results description: Results retrieval operations paths: /enterprise/api/generate_ad_text: post: tags: - Processing summary: Generate AD text description: | 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. operationId: generateAdText requestBody: required: true content: application/json: schema: type: object required: - input properties: input: oneOf: - type: object title: Using Media ID required: - type - media_id properties: type: type: string enum: - media_id default: media_id media_id: type: string format: uuid description: Existing Media ID from upload_media filename: type: string description: Optional filename override - type: object title: Upload from URL required: - type - url properties: type: type: string enum: - url default: url url: type: string format: uri description: Public video URL filename: type: string description: Optional filename override - type: object title: Uploading a Local File required: - type properties: type: type: string enum: - file default: file description: File upload via multipart/form-data discriminator: propertyName: type generation_config: type: object description: Configuration for text generation properties: format: type: string default: vtt enum: - vtt - srt - txt - json - edl description: >- Format used to serialize the text part of the response (descriptions). Audio and video files are returned separately by their respective endpoints. language: type: string default: en-US description: >- Target language (BCP-47 code, e.g. `en-US`). See [Languages and Voices](/api-reference/voices) for the full list of 53 codes. video_category: type: string default: Auto enum: - Auto - Educational Lecture - Educational Kids - Government Meeting - Documentary - Narrative Story - Social Media - Tutorial/How-To - Vlog - Commercial/Advertisement - News - Entertainment - Home Video - Video Call description: >- Provides better audio descriptions with a selected category of the video ad_type: type: string default: extended_ad enum: - extended_ad - standard_ad description: Type of audio description custom_instructions: type: string default: '' description: >- Optional custom prompt to guide the AI (terminology, style, focus areas). When omitted or empty, no custom instructions are applied. read_all_onscreen_text: type: boolean default: false description: > Only applies when `ad_type` is `extended_ad`. When true, forces the model to add all on-screen text to the descriptions instead of summarizing in some cases. auto_fit: type: boolean default: true description: >- Only applies when `ad_type` is `standard_ad`. Fit generated descriptions into detected no-speech zones when possible. allow_descriptions_over_music: type: boolean default: true description: >- Only applies when `ad_type` is `standard_ad`. Allow descriptions to be placed over detected music when no better timing is available. standard_ad_min_cue_length: type: number default: 0.75 minimum: 0.75 maximum: 5 description: > Only applies when `ad_type` is `standard_ad` and `auto_fit` is enabled (the default). Minimum length, in seconds, of a silent (no-speech) gap where a description may be placed. Gaps shorter than this are skipped instead of squeezing text in. Raise it for fewer, longer, more natural descriptions that better fit broadcast-style guidelines; lower it to place more, shorter descriptions in smaller gaps. custom_captions: type: object description: > Optional captions to use for transcript/context instead of auto-generating captions. Send only `content` (required); `format` and `filename` are optional hints. The server normalizes the payload and derives any additional fields it needs. required: - content properties: content: type: string description: >- Captions text (WebVTT, SubRip, or timestamped plaintext). format: type: string enum: - vtt - srt - plaintext description: >- Optional format hint. Auto-detected from `content` or `filename` if omitted. filename: type: string description: >- Optional filename hint (used for format auto-detection when `format` is omitted). examples: media_id: summary: Using existing Media ID value: input: type: media_id media_id: 550e8400-e29b-41d4-a716-446655440000 generation_config: language: en-US format: json ad_type: extended_ad url: summary: Upload from URL value: input: type: url url: https://example.com/video.mp4 generation_config: language: en-US format: vtt ad_type: standard_ad multipart/form-data: schema: type: object required: - input - file properties: input: type: string description: 'JSON string {"type": "file"}' example: '{"type": "file"}' file: type: string format: binary description: Video file to upload generation_config: type: string description: JSON string with configuration example: '{"language": "en-US", "format": "vtt"}' examples: file: summary: Uploading a Local File value: input: '{"type": "file"}' file: '@/path/to/video.mp4' generation_config: '{"language": "en-US", "format": "vtt"}' responses: '200': description: Job created successfully content: application/json: schema: type: object properties: job_id: type: string description: Unique job identifier for tracking status: type: string example: queued description: >- Initial job status. Always `queued` for a fresh submission. media_id: type: string format: uuid description: Media being processed example: job_id: task_abc123xyz status: queued media_id: 550e8400-e29b-41d4-a716-446655440000 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden - feature unavailable or uploaded input exceeds plan limits content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Conflict - referenced media is not ready for generation or failed upload verification content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many requests - rate, queue, concurrency, or plan limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: error: type: string description: >- Primary error field. Many endpoints return a machine-readable value here, while some 409 media-state responses return a human-readable string and place the machine-readable identifier in code code: type: string description: >- Optional machine-readable identifier for responses that separate the human-readable error text from the stable error code, such as upload_not_ready or upload_failed upload_status: type: string description: >- Optional media upload status included on media-state conflict responses message: type: string description: Human-readable error message details: type: string description: Additional error details when available example: error: invalid_input message: video_id is required securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: > API key for authentication. Obtain from your team admin. Example: `X-API-Key: vsk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz` ````