Generate AD Audio

POST

enterprise

api

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": "550e8400-e29b-41d4-a716-446655440000"
  },
  "generation_config": {
    "language": "en-US",
    "voice": "Achernar",
    "audio_track_type": "mixed"
  }
}
'

{
  "job_id": "task_abc123xyz",
  "status": "queued",
  "media_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

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. The response returns a job_id within a few seconds, even for long videos, and the file downloads in the background. If the file can’t be downloaded or is over your plan’s limits, the job fails and /get_results returns upload_failed, video_too_long, file_too_large or no_video_stream. Those jobs are not charged. A request that includes your own description_content still downloads the file before it responds.

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

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": "<VTT/SRT/plaintext>" }`; `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.

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.

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

Using Media ID
Upload from URL

Show child attributes

generation_config

object

Configuration for audio generation

Show child attributes

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

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": "550e8400-e29b-41d4-a716-446655440000"
  },
  "generation_config": {
    "language": "en-US",
    "voice": "Achernar",
    "audio_track_type": "mixed"
  }
}
'

{
  "job_id": "task_abc123xyz",
  "status": "queued",
  "media_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

{
  "error": "invalid_input",
  "message": "video_id is required"
}

API Reference

Media

Text Generation

Audio Generation

Video Generation

Results

Media

Processing

Results

Usage Examples

1. Using an existing Media ID

2. Using a Public URL

3. Uploading a Local File

Generation Config Options

Troubleshooting

Authorizations

Body

Response

​Usage Examples

​1. Using an existing Media ID

​2. Using a Public URL

​3. Uploading a Local File

​Generation Config Options

​Troubleshooting

Authorizations

Body

Response

Usage Examples

1. Using an existing Media ID

2. Using a Public URL

3. Uploading a Local File

Generation Config Options

Troubleshooting