Generate AD Text

POST

enterprise

api

generate_ad_text

curl --request POST \
  --url https://api.viddyscribe.com/enterprise/api/generate_ad_text \
  --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",
    "format": "json",
    "ad_type": "extended_ad"
  }
}
'

{
  "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"
}

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_text \
  -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",
      "ad_type": "extended_ad"
    }
  }'

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.

curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \
  -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": "json",
      "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_text \
  -H "X-API-Key: YOUR_API_KEY" \
  -F 'input={"type": "file"}' \
  -F "file=@/path/to/video.mp4" \
  -F 'generation_config={"language": "en-US", "format": "srt"}'

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.

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
Uploading a Local File

Show child attributes

generation_config

object

Configuration for text 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_text \
  --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",
    "format": "json",
    "ad_type": "extended_ad"
  }
}
'

{
  "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