Skip to main content

​
Generate AD Text

Pick one of the two simple flows below to generate audio description text.
Already uploaded media or using the signed upload flow? Generate with media_id. See Large Local File Upload or API Reference.

​
1. Using a Video from public URL

Upload from a public URL and generate in one step. 
curl -X POST https://api.viddyscribe.com/enterprise/api/generate_ad_text \
  -H "X-API-Key: vsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "url",
      "url": "https://example.com/video.mp4"
    },
    "generation_config": {
      "language": "en-US",
      "ad_type": "extended_ad",
      "format": "vtt",
      "custom_instructions": "Keep descriptions concise and focus on on-screen text."
    }
  }'
Response: 
{
  "job_id": "task_abc123xyz",
  "status": "queued",
  "media_id": "550e8400-e29b-41d4-a716-446655440000"
}
Use the job_id to poll get_results for completion.

​
2. Using a Video from local file

Upload a local file and generate in one 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: vsk_your_api_key_here" \
  -F 'input={"type": "file"}' \
  -F "file=@video.mp4" \
  -F 'generation_config={"language": "en-US", "ad_type": "extended_ad", "format": "vtt", "custom_instructions": "Keep descriptions concise and focus on on-screen text."}'
Response: 
{
  "job_id": "task_abc123xyz",
  "status": "queued",
  "media_id": "660f9511-f30c-52e5-b827-557766551111"
}
Use the job_id to poll get_results for completion. On success, output.content contains the VTT string (or output.segments for JSON format).

​
Tips

  • The default text output format is json. Set format to "vtt" to include a WebVTT string in the response output.
  • Choose standard_ad or extended_ad based on your timing and detail needs. See Standard AD vs Extended AD.
  • Use custom_instructions to guide the AI’s description style (e.g. tone, focus, or length).
  • Set read_all_onscreen_text: true for educational, government, or news content to force the AI to read slides, lower thirds, and on-screen labels verbatim (only applies when ad_type is extended_ad).

​
Retrieve Results

Use the job_id from the previous step to fetch results: 
curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID" \
  -H "X-API-Key: vsk_your_api_key_here"
Example successful response for text jobs (with format: "vtt"): 
{
  "job_id": "task_abc123xyz",
  "status": "done",
  "media_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-09-30T08:00:00Z",
  "updated_at": "2025-09-30T08:10:00Z",
  "output": {
    "format": "vtt",
    "content": "WEBVTT\n\n1\n00:00:00.500 --> 00:00:03.100\nA woman in a yellow top sits at a desk with a laptop.\n\n2\n00:00:03.200 --> 00:00:05.900\nShe looks at the camera and smiles.\n"
  }
}
Example successful response for text jobs (with format: "json"): 
{
  "job_id": "task_abc123xyz",
  "status": "done",
  "media_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-09-30T08:00:00Z",
  "updated_at": "2025-09-30T08:10:00Z",
  "output": {
    "format": "json",
    "segments": [
      { "id": "1", "start_time": 0.500, "end_time": 3.100, "description": "A woman in a yellow top sits at a desk with a laptop." },
      { "id": "2", "start_time": 3.200, "end_time": 5.900, "description": "She looks at the camera and smiles." }
    ]
  }
}