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

# Uploading Large Files

> Upload larger local video files with the signed upload flow, then generate with media_id

## When to Use This Flow?

Use this flow for local video files larger than 32 MB.

Direct multipart upload is supported for smaller files, but larger local files should use the signed upload flow. Your plan's file-size limits still apply.

## Workflow

<Steps>
  <Step title="Request a Signed Upload URL">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.viddyscribe.com/enterprise/api/upload_media \
        -H "X-API-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "input": {
            "type": "signed_url",
            "filename": "video.mp4",
            "content_type": "video/mp4"
          }
        }'
      ```

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

      response = requests.post(
          "https://api.viddyscribe.com/enterprise/api/upload_media",
          headers={"X-API-Key": "YOUR_API_KEY"},
          json={
              "input": {
                  "type": "signed_url",
                  "filename": "video.mp4",
                  "content_type": "video/mp4",
              }
          },
      )
      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        "https://api.viddyscribe.com/enterprise/api/upload_media",
        {
          method: "POST",
          headers: {
            "X-API-Key": "YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            input: {
              type: "signed_url",
              filename: "video.mp4",
              content_type: "video/mp4",
            },
          }),
        }
      );
      console.log(await response.json());
      ```
    </CodeGroup>

    **Response:**

    ```json theme={null}
    {
      "media_id": "550e8400-e29b-41d4-a716-446655440000",
      "upload_url": "https://storage.googleapis.com/bucket/path/to/video.mp4?X-Goog-Signature=...",
      "gcs_path": "users/user_123/videos/video.mp4",
      "status": "pending_upload",
      "content_type": "video/mp4"
    }
    ```
  </Step>

  <Step title="Upload the File Bytes">
    Use the returned `upload_url` to `PUT` the file directly to storage.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PUT "UPLOAD_URL" \
        -H "Content-Type: video/mp4" \
        --upload-file ./video.mp4
      ```

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

      with open("video.mp4", "rb") as f:
          response = requests.put(
              "UPLOAD_URL",
              headers={"Content-Type": "video/mp4"},
              data=f,
          )
      response.raise_for_status()
      ```

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

      const response = await fetch("UPLOAD_URL", {
        method: "PUT",
        headers: { "Content-Type": "video/mp4" },
        body: fs.readFileSync("./video.mp4"),
      });
      if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Notify the API">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.viddyscribe.com/enterprise/api/notify_upload_complete \
        -H "X-API-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "media_id": "550e8400-e29b-41d4-a716-446655440000",
          "gcs_path": "users/user_123/videos/video.mp4"
        }'
      ```

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

      response = requests.post(
          "https://api.viddyscribe.com/enterprise/api/notify_upload_complete",
          headers={"X-API-Key": "YOUR_API_KEY"},
          json={
              "media_id": "550e8400-e29b-41d4-a716-446655440000",
              "gcs_path": "users/user_123/videos/video.mp4",
          },
      )
      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        "https://api.viddyscribe.com/enterprise/api/notify_upload_complete",
        {
          method: "POST",
          headers: {
            "X-API-Key": "YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            media_id: "550e8400-e29b-41d4-a716-446655440000",
            gcs_path: "users/user_123/videos/video.mp4",
          }),
        }
      );
      console.log(await response.json());
      ```
    </CodeGroup>
  </Step>

  <Step title="Poll Upload Status">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.viddyscribe.com/enterprise/api/get_upload_status?media_id=550e8400-e29b-41d4-a716-446655440000&gcs_path=users/user_123/videos/video.mp4" \
        -H "X-API-Key: YOUR_API_KEY"
      ```

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

      response = requests.get(
          "https://api.viddyscribe.com/enterprise/api/get_upload_status",
          headers={"X-API-Key": "YOUR_API_KEY"},
          params={
              "media_id": "550e8400-e29b-41d4-a716-446655440000",
              "gcs_path": "users/user_123/videos/video.mp4",
          },
      )
      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const url = new URL(
        "https://api.viddyscribe.com/enterprise/api/get_upload_status"
      );
      url.searchParams.set("media_id", "550e8400-e29b-41d4-a716-446655440000");
      url.searchParams.set("gcs_path", "users/user_123/videos/video.mp4");

      const response = await fetch(url, {
        headers: { "X-API-Key": "YOUR_API_KEY" },
      });
      console.log(await response.json());
      ```
    </CodeGroup>

    Wait until `upload_status` is `completed`.

    If `canonical_media_id` differs from the original `media_id`, use `canonical_media_id` for generation.
  </Step>

  <Step title="Generate Text, Audio, or Video with media_id">
    After upload verification completes, call a text, audio, or video generation endpoint with `input.type: "media_id"`.

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

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

      response = requests.post(
          "https://api.viddyscribe.com/enterprise/api/generate_ad_text",
          headers={"X-API-Key": "YOUR_API_KEY"},
          json={
              "input": {
                  "type": "media_id",
                  "media_id": "550e8400-e29b-41d4-a716-446655440000",
              },
              "generation_config": {"language": "en-US", "format": "json"},
          },
      )
      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": "YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            input: {
              type: "media_id",
              media_id: "550e8400-e29b-41d4-a716-446655440000",
            },
            generation_config: { language: "en-US", format: "json" },
          }),
        }
      );
      console.log(await response.json());
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Reference Pages

* [Upload Media](/api-reference/media/upload-media)
* [Notify Upload Complete](/api-reference/media/notify-upload-complete)
* [Get Upload Status](/api-reference/media/get-upload-status)
* [Generate AD Text](/api-reference/processing/generate-audio-description-text)
* [Generate AD Audio](/api-reference/processing/generate-audio-description-audio)
* [Generate AD Video](/api-reference/processing/generate-audio-description-video)