# Upload API

> Upload local video files for AI Clipping, Summarization, Video Notes, Transcription, Find Moments, and Video Enhancer.

## Upload API

The Upload API lets you upload local video files to WayinVideo. After uploading, use the returned file identifier as the `video_url` in other API endpoints (AI Clipping, Find Moments, Video Summarization, Video Notes, Video Transcription, Video Enhancer).

**File Size Limit:** Single file size limit for local uploads: 5 GB. If you need a higher limit, please contact us at [wayinvideo@wayin.ai](mailto:wayinvideo@wayin.ai).

**Supported formats:** You must upload a valid video file. Currently supported formats: **avi**, **mp4**, **mov**, **webm**. Uploading other formats may cause task processing to fail after submission.

### Upload Flow

1. **Request** a pre-signed upload URL by providing file metadata
2. **Upload** the file directly to the pre-signed URL using a `PUT` request
3. **Use** the returned `identity` value as `video_url` in subsequent API calls

---

## Get Upload URL

Request a temporary upload URL for a local file.

```http
POST https://wayinvideo-api.wayin.ai/api/v2/upload/single-file
```

### Request Body

| Parameter | Type   | Required | Default | Description                                      |
| --------- | ------ | -------- | ------- | ------------------------------------------------ |
| `name`    | string | Yes      | —       | File name with extension (e.g. `"my-video.mp4"`) |

### Example Request

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/upload/single-file \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "name": "sample-video.mp4"
  }'
```

### Response

```json
{
  "data": {
    "upload_url": "https://storage.example.com/upload/presigned-url...",
    "identity": "file_abc123"
  }
}
```

| Field        | Type   | Description                                                                                                                                               |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upload_url` | string | Pre-signed URL for uploading the file. This URL expires after **1 hour** — please complete the upload within that time. If it expires, request a new URL. |
| `identity`   | string | File identifier to use as `video_url` in other APIs                                                                                                       |

---

## Upload the File

Use the `upload_url` to upload your file with a `PUT` request. The `@` in `--data-binary` is followed by the local file path:

```bash
curl -X PUT "https://storage.example.com/upload/presigned-url..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/Users/me/Videos/sample-video.mp4
```

> **Note:** If you upload again using the same `upload_url`, the new file will overwrite the previous one. Each single file must not exceed **5 GB**.

---

## Use the Uploaded File

After uploading, pass the `identity` value as the `video_url` when submitting tasks.

> **Note:** Each `identity` is valid for **24 hours**. When you have sufficient quota, you can use the same `identity` to submit multiple tasks within 24 hours.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "THE_IDENTITY_VALUE",
    "enable_export": false
  }'
```

---

## FAQ

### When should I upload a local file vs. pass a source URL?

If your video already exists on a supported platform (YouTube, Vimeo, TikTok, Zoom, etc.), pass the URL directly to the processing endpoint — no upload needed. Use the Upload API only for files that are not yet hosted on a supported source.

### What is the maximum upload file size?

5 GB per file. Contact [wayinvideo@wayin.ai](mailto:wayinvideo@wayin.ai) if your use case needs a higher limit.

### Which file formats are supported?

`mp4`, `mov`, `webm`, `avi`. Other formats may fail during processing.

### Does upload count toward my plan storage quota?

Yes — uploaded files consume storage on your subscription plan. See [Subscription Plans](https://wayin.ai/wayinvideo/settings/plan) for per-plan storage and per-file size limits.

### How do I use the uploaded file in other API calls?

After uploading, pass the returned file identifier as the `video_url` field on any supported processing endpoint — [AI Clipping](https://wayin.ai/api-docs/ai-clipping/), [Find Moments](https://wayin.ai/api-docs/find-moments/), [Video Summarization](https://wayin.ai/api-docs/video-summarization/), [Video Notes](https://wayin.ai/api-docs/video-notes/), [Video Transcription](https://wayin.ai/api-docs/video-transcription/), or [Video Enhancer](https://wayin.ai/api-docs/video-enhancer/).