Uploading Large Files

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

Request a Signed Upload URL

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

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())

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());

Response:

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

Upload the File Bytes

Use the returned upload_url to PUT the file directly to storage.

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file ./video.mp4

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()

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}`);

Notify the API

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

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())

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());

Poll Upload Status

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"

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())

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());

Wait until upload_status is completed.If canonical_media_id differs from the original media_id, use canonical_media_id for generation.

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

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

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())

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());

Getting Started with the API

API Guides

Dashboard Guide

Help & Resources

Uploading Large Files

When to Use This Flow?

Workflow

​When to Use This Flow?

​Workflow

​Related Reference Pages

When to Use This Flow?

Workflow

Related Reference Pages