> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Video

> Ingest video, audio, and images from URLs or local files into VideoDB collections

## Quick Example

<CodeGroup>
  ```python Python theme={null}
  import videodb

  conn = videodb.connect()
  coll = conn.get_collection()

  video = coll.upload("https://example.com/video.mp4")
  print(video.id)  # m-xxx
  ```

  ```javascript Node.js theme={null}
  import { connect } from 'videodb';

  const conn = await connect();
  const coll = await conn.getCollection();

  const video = await coll.uploadURL("https://example.com/video.mp4");
  console.log(video.id);  // m-xxx
  ```
</CodeGroup>

***

## Upload Methods

### From URL

Upload directly from any accessible URL (S3, YouTube, public links):

<CodeGroup>
  ```python Python theme={null}
  # Video
  video = coll.upload(url="https://youtu.be/a9__D53WsUs")

  # Audio
  from videodb import MediaType
  audio = coll.upload(
      url="https://example.com/podcast.mp3",
      media_type=MediaType.audio
  )

  # Image
  image = coll.upload(
      url="https://example.com/frame.jpg",
      media_type=MediaType.image
  )
  ```

  ```javascript Node.js theme={null}
  import { MediaType } from 'videodb';

  // Video
  const video = await coll.uploadURL({ url: "https://youtu.be/a9__D53WsUs" });

  // Audio
  const audio = await coll.uploadURL({
      url: "https://example.com/podcast.mp3",
      mediaType: MediaType.audio
  });

  // Image
  const image = await coll.uploadURL({
      url: "https://example.com/frame.jpg",
      mediaType: MediaType.image
  });
  ```
</CodeGroup>

### From Local File

Upload files from your local filesystem:

<CodeGroup>
  ```python Python theme={null}
  video = coll.upload(file_path="./meeting-recording.mp4")
  ```

  ```javascript Node.js theme={null}
  const video = await coll.uploadFile({ filePath: "./meeting-recording.mp4" });
  ```
</CodeGroup>

***

## Media Types

| Type  | ID Prefix | Use Case                       |
| :---- | :-------- | :----------------------------- |
| Video | `m-xxx`   | Primary content, full playback |
| Audio | `a-xxx`   | Podcasts, voice recordings     |
| Image | `img-xxx` | Thumbnails, frames             |

***

## Upload Response

After upload, you receive a media object with:

| Property        | Description                               |
| :-------------- | :---------------------------------------- |
| `id`            | Unique identifier (m-xxx, a-xxx, img-xxx) |
| `collection_id` | Parent collection ID                      |
| `name`          | File name                                 |
| `length`        | Duration in seconds (video/audio)         |
| `stream_url`    | HLS stream URL (video)                    |
| `player_url`    | Web player URL (video)                    |

***

## Async Uploads with Callbacks

For production workflows, use callbacks to handle upload completion:

<CodeGroup>
  ```python Python theme={null}
  video = coll.upload(
      url="https://example.com/large-video.mp4",
      callback_url="https://your-backend.com/webhooks/upload"
  )
  ```

  ```javascript Node.js theme={null}
  const video = await coll.uploadURL({
      url: "https://example.com/large-video.mp4",
      callbackUrl: "https://your-backend.com/webhooks/upload"
  });
  ```
</CodeGroup>

Your webhook receives:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "m-xxx",
    "collection_id": "c-xxx",
    "name": "large-video.mp4",
    "stream_url": "https://stream.videodb.io/...",
    "player_url": "https://console.videodb.io/player?url=..."
  }
}
```

***

## What You Can Build

<CardGroup cols={2}>
  <Card title="Faceless Video Creator" icon="film" href="/examples-and-tutorials/content-factory/faceless-video-creator">
    Upload assets and compose complete AI-generated videos
  </Card>

  <Card title="TikTok Lyric Videos" icon="music" href="/examples-and-tutorials/content-factory/tiktok-lyric-video">
    Upload music and create viral vertical clips with synced lyrics
  </Card>

  <Card title="Intro & Outro Automation" icon="play" href="/examples-and-tutorials/programmatic-editing/intro-outro">
    Upload brand assets and automatically add to all videos
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card icon="folder" title="Create Collection" href="/pages/ingest/files-and-collections/create-collection">
    Organize uploads into collections
  </Card>

  <Card icon="folder" title="Collection Patterns" href="/pages/ingest/files-and-collections/collection-patterns">
    Batching, retries, and production patterns
  </Card>
</CardGroup>