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

# Generate AD Text

> Quick guide to generate audio description text via URL or local file

## Generate AD Text

Pick one of the two simple flows below to generate audio description text.

<Note>
  Already uploaded media or using the signed upload flow? Generate with `media_id`. See [Large Local File Upload](/large-local-file-upload) or [API Reference](/api-reference/processing/generate-audio-description-text).
</Note>

### 1. Using a Video from public URL

Upload from a public URL and generate in one step.

<CodeGroup>
  ```bash cURL theme={null}
  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."
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.viddyscribe.com/enterprise/api/generate_ad_text",
      headers={"X-API-Key": "vsk_your_api_key_here"},
      json={
          "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.",
          },
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.viddyscribe.com/enterprise/api/generate_ad_text",
    {
      method: "POST",
      headers: {
        "X-API-Key": "vsk_your_api_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        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.",
        },
      }),
    }
  );
  console.log(await response.json());
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<Note>
  Direct multipart upload supports local files up to 32 MB. For larger local files, see [Large Local File Upload](/large-local-file-upload).
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  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."}'
  ```

  ```python Python theme={null}
  import json
  import requests

  with open("video.mp4", "rb") as f:
      response = requests.post(
          "https://api.viddyscribe.com/enterprise/api/generate_ad_text",
          headers={"X-API-Key": "vsk_your_api_key_here"},
          files={"file": f},
          data={
              "input": json.dumps({"type": "file"}),
              "generation_config": json.dumps({
                  "language": "en-US",
                  "ad_type": "extended_ad",
                  "format": "vtt",
                  "custom_instructions": "Keep descriptions concise and focus on on-screen text.",
              }),
          },
      )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  import fs from "node:fs";

  const form = new FormData();
  form.append("input", JSON.stringify({ type: "file" }));
  form.append("file", new Blob([fs.readFileSync("video.mp4")]), "video.mp4");
  form.append("generation_config", JSON.stringify({
    language: "en-US",
    ad_type: "extended_ad",
    format: "vtt",
    custom_instructions: "Keep descriptions concise and focus on on-screen text.",
  }));

  const response = await fetch(
    "https://api.viddyscribe.com/enterprise/api/generate_ad_text",
    {
      method: "POST",
      headers: { "X-API-Key": "vsk_your_api_key_here" },
      body: form,
    }
  );
  console.log(await response.json());
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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](/help/standard-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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID" \
    -H "X-API-Key: vsk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.viddyscribe.com/enterprise/api/get_results",
      headers={"X-API-Key": "vsk_your_api_key_here"},
      params={"job_id": "TASK_ID"},
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.viddyscribe.com/enterprise/api/get_results?job_id=TASK_ID",
    { headers: { "X-API-Key": "vsk_your_api_key_here" } }
  );
  console.log(await response.json());
  ```
</CodeGroup>

Example successful response for text jobs (with `format: "vtt"`):

```json theme={null}
{
  "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"`):

```json theme={null}
{
  "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." }
    ]
  }
}
```