Skip to main content
POST
/
enterprise
/
api
/
generate_ad_audio
Generate AD audio
curl --request POST \
  --url https://api.viddyscribe.com/enterprise/api/generate_ad_audio \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "input": {
    "type": "media_id",
    "media_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "filename": "<string>"
  },
  "generation_config": {
    "format": "json",
    "language": "en-US",
    "video_category": "Auto",
    "voice": "Achernar",
    "custom_instructions": "",
    "auto_fit": true,
    "allow_descriptions_over_music": true,
    "volume_option": "auto",
    "volume_level_db": -5,
    "audio_track_type": "mixed",
    "description_content": "<string>"
  }
}
'
{
  "job_id": "task_abc123xyz",
  "status": "queued",
  "media_id": "550e8400-e29b-41d4-a716-446655440000"
}

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.

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

OptionTypeDescription
auto_fitbooleanFits descriptions into detected no-speech zones when possible.
allow_descriptions_over_musicbooleanAllows descriptions over detected music when no better timing is available.
custom_captionsobjectUses provided captions for transcript/context instead of auto-generating them. Send { "content": "<VTT/SRT/plaintext>" }; format and filename are optional hints. The server parses, validates, and normalizes the cues automatically.
volume_optionauto or maxUse max to set a target max peak level for the AD track, or auto for the default.
volume_level_dbnumberMax peak level in dBFS when volume_option is max. Supported range is -10 to 0.
audio_track_typemixed or ad_onlyWhich 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.
ErrorHTTP StatusDescription
upload_not_ready409Returned in the code field when the referenced media is still being verified after upload. Retry shortly.
upload_failed409Returned in the code field when the referenced media failed upload verification. Re-upload the video and try again.
concurrency_limit_exceeded429Too many concurrent submissions are being validated for the current team. Retry after a short delay.

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Obtain from your team admin.

Example: X-API-Key: vsk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Body

​
input
Using Media ID · object
required
​
generation_config
object

Configuration for audio generation

Response

Job created successfully

​
job_id
string

Unique job identifier for tracking

​
status
string

Initial job status. Always queued for a fresh submission.

Example:

"queued"

​
media_id
string<uuid>

Media being processed