Skip to main content
POST
/
enterprise
/
api
/
generate_ad_video
Generate AD video
curl --request POST \
  --url https://api.viddyscribe.com/enterprise/api/generate_ad_video \
  --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": "vtt",
    "language": "en-US",
    "video_category": "Auto",
    "voice": "Achernar",
    "ad_type": "extended_ad",
    "custom_instructions": "",
    "read_all_onscreen_text": false,
    "auto_fit": true,
    "allow_descriptions_over_music": true,
    "volume_option": "auto",
    "volume_level_db": -5,
    "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.

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

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.

​
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 video 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