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

# File Uploads

> Upload images and videos for use in generation requests

## Overview

Some generation types require file inputs (images for image-to-video, videos for video extension, etc.). ModelHunter.AI uses a **two-step upload flow** with signed URLs.

## Upload Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant ModelHunter
    participant R2 Storage

    Client->>ModelHunter: POST /api/v1/files/upload-url
    ModelHunter-->>Client: { upload_url, file_id }
    Client->>R2 Storage: PUT upload_url (file bytes)
    R2 Storage-->>Client: 200 OK
    Client->>ModelHunter: POST /api/v1/files/{file_id}/complete
    ModelHunter-->>Client: { id, url }
```

### Step 1: Get a Signed Upload URL

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/files/upload-url \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 2048576
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "upload_url": "https://storage.modelhunter.ai/uploads/file_abc123?X-Amz-Signature=xxx",
    "file_id": "file_abc123",
    "expires_at": "2025-01-15T10:15:00Z"
  }
}
```

### Step 2: Upload the File

Upload the file directly to the signed URL using a `PUT` request:

```bash theme={null}
curl -X PUT "https://storage.modelhunter.ai/uploads/file_abc123?X-Amz-Signature=xxx" \
  -H "Content-Type: image/jpeg" \
  --data-binary @my-image.jpg
```

### Step 3: Confirm the Upload

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/files/file_abc123/complete \
  -H "Authorization: Bearer river_live_xxx"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "file_abc123",
    "url": "https://cdn.modelhunter.ai/files/file_abc123.jpg",
    "filename": "my-image.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 2048576,
    "created_at": "2025-01-15T10:00:30Z"
  }
}
```

## Using Uploaded Files

Pass the file URL in your generation request:

```bash theme={null}
curl -X POST https://api.modelhunter.ai/api/v1/vidu/image-to-video \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "input": {
      "image_url": "https://cdn.modelhunter.ai/files/file_abc123.jpg",
      "prompt": "A cat walking gracefully",
      "duration": 4
    }
  }'
```

<Tip>
  You can also pass any publicly accessible URL as `image_url` or `video_url` — file upload is only needed for local files.
</Tip>

## Supported Formats

### Images

| Property         | Requirement          |
| ---------------- | -------------------- |
| Formats          | PNG, JPEG, JPG, WebP |
| Min resolution   | 128 x 128            |
| Max aspect ratio | 4:1 or 1:4           |
| Max file size    | 50 MB                |

### Video

| Property      | Requirement     |
| ------------- | --------------- |
| Formats       | MP4             |
| Duration      | 1 — 600 seconds |
| Max file size | 500 MB          |